A request to POST /v1/events can time out after PayloadPuffin stored the event but before your application read the 202. Send it again without a key and you get a second event, and your destinations get the webhook twice. An idempotency key makes that retry safe: every repeat with the same key returns the first event's receipt.
Send with a key
Choose one key for the record that caused the event, and send that same key on every retry. A UUID works well: generate it once, store it with the record, and reuse it. A value generated fresh for each try doesn't work, because the retry would carry a different key. A key is 1 to 48 characters. A UUID is 36, so there's room to build a key in your own format. A longer key is refused with
400.Send the key in the
Idempotency-Keyheader. The event body has no field for it, and an unknown body field is refused with400.send-event.sh curl -X POST "https://api.payloadpuffin.com/v1/events" \ -H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: customer-1042-created" \ --data-binary @send-event.jsonStore the
eventIdfrom the202receipt.
Retry a failed send
If the request fails without a receipt, send the same request again with the same key. That covers a network error, a timeout, a 5xx, a 502 with the code dependency_failed, and a 503 with the code service_unavailable.
A 503 means PayloadPuffin couldn't check the key, so it accepted nothing. It sets Retry-After. Wait that long and send the same request with the same key.
A 409 with the code conflict means another request with this key is still being processed. Wait the number of seconds in the Retry-After header, then send again. Nothing is wrong with your event. The 409 stops when the first request finishes, or when its claim on the key lapses 60 seconds after it was made.
A 400, 401, 403 or 413 gets the same answer every time you send the same request. Fix the request first.
A repeat that arrives after the event was accepted gets 202 with the original receipt: the same eventId, type, receivedAt and bytes. PayloadPuffin doesn't create or deliver a second event.
What a key matches
A key matches on the app and the key alone:
- One app. The same key in your staging app and your production app names two different events.
- First accepted wins. PayloadPuffin doesn't compare the content. A repeat with a different
type,payloadorchannelsreturns the first event's receipt and is otherwise ignored. It isn't a conflict, and it doesn't change the first event. To send a different event, use a different key. - 24 hours after acceptance. A repeat doesn't extend that window. After it, the same key creates a new event.
A request that fails before PayloadPuffin accepted it doesn't use up the key. The next request with that key can still be accepted.
Webhooks to a source
A request to a source's URL is deduplicated the same way, with two differences:
- The key is the
Idempotency-Keyheader, or else thewebhook-idheader that many services send with each webhook. When a request has both,Idempotency-Keywins. - It matches per source, not per app, and it can be any length. The same
webhook-idsent to two sources creates two events.
A repeat within 24 hours gets 202 with the first event's ID.
What a key doesn't cover
The key protects your send to PayloadPuffin, not the webhooks that follow. A delivery can reach a destination more than once, for example when the destination processed a request but timed out before answering. Your receiver must handle duplicates with the webhook-id header described in Attempts.