GuidesCore concepts
Idempotency
Send events safely more than once, and process received events exactly once.
Networks fail. Idempotency makes retries safe on both sides of a webhook.
When sending events
Pass an Idempotency-Key header (or the idempotencyKey option in the SDKs) when you send an event. If you send the same key again within 24 hours, Relay returns the original event instead of creating a new one.
curl https://api.relay.dev/v1/events \
-H "Authorization: Bearer $RELAY_API_KEY" \
-H "Idempotency-Key: invoice-1042-paid" \
-H "Content-Type: application/json" \
-d '{"type": "invoice.paid", "data": {"invoice_id": "in_1042"}}'Build the key from your own data, such as invoice-1042-paid, not from a random value. That way a crashed job that runs again produces the same key.
When receiving events
Relay delivers at least once, so your endpoint may see the same event twice. Store the IDs you've processed and skip duplicates:
const event = verifyWebhook({ payload, header, secret });
await db.transaction(async (tx) => {
const inserted = await tx.insert(processedEvents).values({ id: event.id }).onConflictDoNothing();
if (inserted.rowCount === 0) return; // already handled
await fulfillOrder(tx, event.data);
});Keep the ID insert and your side effects in the same transaction. If the work fails, the ID isn't saved and the retry processes it again.