Webhook receiver

What the webhook receiver is

The Tideflow webhook receiver is a Supabase Edge Function that gives each business a single, managed webhook destination URL. Instead of building and hosting your own endpoint, you deploy the receiver function and query deliveries from a database table.

When to use the receiver

• You want a managed destination without setting up external infrastructure.
• You prefer querying deliveries from a database table over building a real-time HTTP handler.
• You want to process webhook events on your own schedule (batch processing, periodic polling).

Components

• Edge Function — tideflow-receiver, a Supabase Edge Function that receives and validates deliveries.
• Inbox table — webhook_receiver_inbox, a database table where validated deliveries are stored.
• Receiver token— A per-endpoint token used to look up the correct endpoint for incoming deliveries.

Setup

1. Deploy the database schema and function

supabase db push
supabase functions deploy tideflow-receiver --project-ref <your-project-ref>

2. Create a receiver URL for your endpoint

scripts/create-webhook-receiver-endpoint.sh \
  --project-ref <your-project-ref> \
  --endpoint-id <webhook_endpoints.id>

This generates a URL containing the receiver token. Use this URL as the webhook endpoint in your Tideflow integration settings.

How it works

1. Tideflow sends a signed webhook delivery to your receiver URL (same HMAC mechanism as standard webhooks).
2. The Edge Function extracts the receiver token from the URL and looks up the endpoint.
3. The function verifies the HMAC signature using the endpoint's signing secret.
4. If valid, the delivery is stored in the webhook_receiver_inbox table.
5. The function returns a 200 response so Tideflow marks the delivery as successful.

Querying deliveries

Query the inbox table to see received deliveries:

SELECT
  received_at,
  business_id,
  endpoint_id,
  event_type,
  delivery_id,
  retry_attempt
FROM public.webhook_receiver_inbox
ORDER BY received_at DESC
LIMIT 50;

Security model

• The Edge Function has verify_jwtdisabled — it authenticates via the URL token and HMAC headers instead.
• The receiver token is for endpoint lookup only. Delivery authenticity is verified through the HMAC signature.
• Keep receiver URLs private. They contain a bearer-like token.
• The webhook_receiver_inbox table is accessible only with the service role. Anonymous and authenticated Supabase clients cannot read it directly.
• An optional replay window setting (WEBHOOK_RECEIVER_MAX_SKEW_SECONDS, default 300 seconds) rejects deliveries with timestamps too far in the past.

Building your own receiver

If you prefer to build a custom receiver endpoint instead of using the managed one, follow these guidelines:

• Verify the X-Tideflow-Signature header before processing. See webhook authentication and delivery for the signature format.
• Use X-Tideflow-Delivery-Id to deduplicate deliveries.
• Respond with a 2xx status within 8 seconds to avoid timeout retries.
• Parse X-Tideflow-Event to route events to appropriate handlers.
• Store the raw payload before doing heavy processing. Return the success response first, then process asynchronously.