​

Troubleshooting: duplicate webhook events and consumer-side dedup

​

Symptom map

​

How Orbit emits a duplicate: the dedup model

• Duplicate on retry. A retry is only started when Orbit did not see a 2xx in time. If your handler did its side effect and then timed out — or returned the ack after Orbit’s per-endpoint timeout_seconds (30-second default) — the retry you receive is a duplicate of an event you already processed.
• Duplicate on replay. Replay re-dispatches the stored payload through the same pipeline, by hand. It works on succeeded rows too: that is the feature, and it always re-sends the same event id.

• The envelope id — "id": "evt_..." in the JSON body.
• The Idempotency-Key header — mirrors body.id, so you can dedup before parsing the body.

​

The durable-consumer pattern

1. Verify the signature, then read body.id (or the Idempotency-Key header — same string).
2. Persist the id into a table or key store with a unique constraint, keeping it for at least 7 days (the full retry window plus the DLQ retention window).
3. Ack immediately. If the insert hit the unique constraint, the event is a duplicate: still return 200. A fast duplicate ack stops the retry cadence and does not re-fire your billable work.
4. Process through a queue. Push the event onto your own worker queue and let the worker, not the HTTP handler, run the side effect. If the worker crashes, the event retries on your side — Orbit never has to.

// In your POST handler — ack in well under 30 s, every time
async function onOrbitWebhook(req, res) {
  verifySignature(req);                       // 401 + stop on failure
  const eventId = req.body.id;                // "evt_..." — or header Idempotency-Key
  const inserted = await seen.insertIgnore(eventId);  // unique ON body.id
  if (!inserted) return res.status(200).json({ duplicate: true });
  await queue.enqueue(req.body);              // side effects belong to a worker
  return res.status(200).json({ received: true });
}

• The only correct key is the event id — never the delivery id (each attempt has its own), never a hash of the payload body (the same logical event can legitimately be replayed with identical bytes, and identical bytes keyed wrong still collapse into one row).
• Ack the duplicate, don’t 4xx it. Returning anything but 2xx burns retry budget on an event you already processed and can push a healthy endpoint toward auto-disable (50 consecutive failures).

​

Replay-side dedup

• DLQ requeue is safe by construction. POST /api/v1/webhooks/dlq/{deliveryId}/requeue only moves rows that never succeeded back into the retry scheduler — your consumer has not seen those event ids yet.
• Single-delivery replay — POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/replay — re-sends one stored event. If the original attempt succeeded, the consumer’s event-id insert collapses it to a no-op; coverage is not lost because the key is the same.
• Bulk replay over a window — POST /api/v1/webhooks/{id}/replay-range — is the dedup-critical case. The window covers every stored delivery, not just failed ones, so the burst contains a share of duplicates by definition. Keep the window tight around the outage, scope it with eventTypeFilter where the outage was event-specific, and let the durable-consumer pattern above absorb the share that already succeeded. Replaying a wide window to a non-durable consumer is the one case that turns a recovery tool into a double-processing storm.

​

Case studies

​

Case 1 — duplicate message.delivered

curl -G "https://api.orbit.devotel.io/api/v1/webhooks/{id}/deliveries" \
  -H "X-API-Key: dv_live_sk_..." \
  --data-urlencode "event_type=message.delivered"

​

Case 2 — duplicate conference.participant_joined

​

What to send support

• Event id (evt_...) from the duplicate pair — the single strongest signal.
• Delivery ids (wdl_... / the delivery row ids) of both attempts, from the deliveries list.
• Consumer-side timestamps — when your endpoint received each attempt and which status code it returned, in UTC.
• Webhook endpoint id and tenant id (Settings → Organization).
• For replay-caused duplicates, the job id and the from/to window you replayed.

​

See also

• Troubleshooting: failed webhook deliveries, retries, DLQ, and replay — the failure-and-recovery loop this page deliberately skips.
• Build a durable webhook consumer — the worked receiver that implements the pattern above.
• Webhook event payloads — the envelope and the Idempotency-Key header contract.
• Webhook security — delivery, retry, and signature semantics.
• Webhook deliveries: explore, inspect, replay — the dashboard surfaces for reading attempts.