Idempotency keys

Network calls retry. Without dedup, that means duplicate events for anyone downstream. Webhook Relay supports the standard Idempotency-Key header on event ingest: pass the same key twice within 24 hours and you get back the original response, not a new event.

Using it

curl -X POST https://api.webhook-relay.dcsuniverse.com/v1/events \
  -H "Authorization: Bearer whk_live_..." \
  -H "Idempotency-Key: order-42-created" \
  -d '{"type":"order.created","payload":{"order_id":42}}'

The first call returns 202 with an event ID. The second call with the same key returns the same 202 with the same event ID — no new event is created, no subscriptions are notified again.

Choosing a good key

• Tie it to the business event, not the request. Use order-42-created, not a random UUID per request. A retry from your application should produce the same key.
• Keep it under 255 bytes. The server truncates longer keys.
• Scope it to your workspace. Keys are unique per-workspace; two workspaces can use the same key without colliding.

Different payload, same key

Reusing a key with a different request body returns 409 Conflict. Same key + same fingerprint is a replay; same key + different fingerprint is a bug worth flagging.

{
  "type": "https://webhook-relay.dcsuniverse.com/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Idempotency-Key was already used with a different payload."
}

The window

Records expire 24 hours after they were written. Past the window, the same key + same payload produces a new event ID — you're starting fresh. If your retry horizon is longer than a day, store the resulting event ID on your side and check before re-sending.