Receive Toast order events, validate signatures, enforce idempotency, and write to Supabase with production-grade error handling.
Toast Webhook Configuration
Toast delivers order events via HTTPS POST to a URL you register in the Toast developer portal. Enable the orders topic and specify the exact events you need (order created, updated, paid). Use a single endpoint and route internally rather than creating separate URLs per event type.
Record the webhook secret Toast provides; it is required for signature validation and is never rotated automatically. Store it as an encrypted environment variable in your deployment platform.
Endpoint Implementation with Cloudflare Workers
Deploy the handler as a Cloudflare Worker to keep latency low and avoid cold-start issues common with serverless functions. The worker must respond with 2xx within Toast’s timeout window or the delivery will be retried.
Accept only POST requests and immediately return 200 after successful processing. Return 4xx for validation failures that should not be retried and 5xx only for transient Supabase errors.
Signature Validation and Payload Parsing
Toast signs the request body with HMAC-SHA256 using the shared secret. Compute the signature on the raw body bytes before any JSON parsing and compare it to the X-Toast-Signature header using a constant-time comparison.
const signature = request.headers.get('X-Toast-Signature');
const body = await request.text();
const hmac = crypto.createHmac('sha256', secret);
hmac.update(body);
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(hmac.digest('hex')))) {
return new Response('Invalid signature', { status: 401 });
}Parse the body only after validation. Extract the order GUID, event type, and timestamp for downstream processing.
Idempotent Writes to Supabase
Toast guarantees at-least-once delivery, so the same order GUID may arrive multiple times. Use the Toast order GUID as the primary key in your Supabase orders table and perform an upsert. This prevents duplicate rows without requiring additional application-level locks.
Store the raw payload alongside normalized fields so you can reprocess later if the schema changes. See Resilient API Workflows: Retries, Idempotency, Rate Limits, and Webhooks for patterns that survive network partitions between the worker and Supabase.
Reconciliation and Failure Modes
Webhooks can be delayed or lost during Toast maintenance windows. Implement a nightly reconciliation job that pulls recent orders via the Toast REST API and compares them against your Supabase table. Flag any discrepancies for manual review.
The most common production failure is partial order data arriving before all line items are finalized. Store orders with a status field and only mark them complete once a paid or closed event arrives. Read the full reconciliation discussion in Integrating POS Systems: Square, Clover, Toast, and the Reconciliation Trap.
Deployment Checklist
Add the worker URL to the Toast webhook configuration and test with their sandbox. Enable Supabase row-level security so the worker service role can insert but public clients cannot. Monitor worker logs for 5xx responses and set up alerts when retry queues exceed a threshold.
Keep the handler stateless. All state lives in Supabase so you can redeploy or scale the worker without data loss.