Retries and ordering

​

What counts as a failed webhook delivery

​

The webhook retry schedule on Flexprice Cloud

​

Retries on self-hosted native delivery

​

Replaying a failed webhook delivery

​

Handling duplicate webhook deliveries

• Key on svix-id. It is unique per message and constant across retries. Keep it for longer than the retry window: the schedule above runs for about 28 hours after the first attempt, so a one-day TTL expires before the last retries arrive. Three days is a safe minimum. A dashboard replay after the record expires is processed as new.
• Or key on the object. For state changes, event_type plus the object’s id plus its updated_at identifies the change. This also protects against two different messages that describe the same state.
• Make the effect idempotent. “Set invoice inv_123 to paid” can run twice safely. “Add 100 credits” cannot; look up the wallet transaction ID from the payload before crediting.

​

Webhook delivery ordering

• Compare timestamps. Each object carries updated_at. Ignore a message whose updated_at is older than what you already stored for that object, and make that comparison part of the write so a concurrent worker cannot slip between the two.
• Read the status from the payload, not the event name. invoice.update tells you an invoice changed; invoice.invoice_status and invoice.payment_status in the body tell you what it is now.
• Fetch when in doubt. If two messages disagree, call the API for the object’s current state. GET /invoices/{id} is cheap and always right.

​

A webhook handler shape that survives retries

async function process(deliveryId: string, event: WebhookEvent) {
  const obj = event[objectKeyFor(event.event_type)];  // invoice, payment, subscription, ...

  await db.transaction(async (tx) => {
    // Insert, not a read: two workers holding the same delivery cannot both pass this
    if (!(await tx.recordDelivery(deliveryId))) return; // INSERT ... ON CONFLICT DO NOTHING

    // The comparison lives inside the write, so an older message that arrives late
    // cannot overwrite a newer snapshot. The insert path handles an object whose
    // first message is an update.
    await tx.run(
      `INSERT INTO objects (id, updated_at, data)
            VALUES ($1, $2, $3)
       ON CONFLICT (id) DO UPDATE
              SET updated_at = EXCLUDED.updated_at, data = EXCLUDED.data
            WHERE objects.updated_at < EXCLUDED.updated_at`,
      [obj.id, obj.updated_at, obj],
    );
  });
}

• The dedupe check is an insert. Calling seen() and then markSeen() as separate statements leaves a window where two workers handed the same delivery both pass the check and both run the side effects. Svix can redeliver while your first attempt is still queued, so that window is real. A unique constraint on the delivery ID closes it.
• The timestamp comparison is part of the write. Loading the row, comparing it in application code, and saving is three statements. Two workers can both pass the comparison, and the one carrying the older snapshot can commit last. A conditional update decides it in one statement. Taking a row lock before the read works too, as long as you hold it until the write commits.
• Both run in one transaction. A crash cannot then apply one without the other, so you do not have to reason about whether saving or marking first is the safer order.

​

Monitoring webhook delivery health

Signature verification

Test webhooks locally