Delivery idempotency

Webhook delivery is at-least-once. Your handler will occasionally see the same delivery twice — a network blip after your handler completed, a retry that crossed paths with your 2xx, a manual replay during debugging. Make duplicates a no-op.

This page is about delivery-side idempotency: deduping repeats of the same webhook event on your server. For request-side idempotency — retrying a POST to the Awardee API safely with Idempotency-Key — see Idempotency. Same idea, different direction.

The dedupe key

Every delivery carries a unique id in the X-Awardee-Delivery header. The same id is reused across retry attempts of the same event — so seeing it twice means the same logical event, and you should skip the work. A different id, even for what looks like “the same” payload, is a different event (likely two genuine state changes in quick succession). Process it.

The pattern

Store seen delivery ids in a small table. Insert with ON CONFLICT DO NOTHING on receipt. If no row was inserted, skip the rest of the handler.

CREATE TABLE webhook_deliveries_seen (
  id           TEXT PRIMARY KEY,
  event_type   TEXT NOT NULL,
  received_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Optional: keep the table small.
CREATE INDEX ON webhook_deliveries_seen (received_at);

Node + Postgres

import { Pool } from "pg"
const db = new Pool()

export async function handleWebhook(req, res) {
  const deliveryId = req.header("X-Awardee-Delivery")
  const eventType = req.header("X-Awardee-Event")

  const { rowCount } = await db.query(
    `INSERT INTO webhook_deliveries_seen (id, event_type)
     VALUES ($1, $2)
     ON CONFLICT (id) DO NOTHING`,
    [deliveryId, eventType],
  )

  if (rowCount === 0) {
    // Already processed — acknowledge silently.
    return res.status(200).end()
  }

  await processEvent(eventType, req.body)
  return res.status(200).end()
}

FastAPI + asyncpg

@app.post("/webhooks/awardee")
async def handle_webhook(request: Request):
    delivery_id = request.headers["X-Awardee-Delivery"]
    event_type = request.headers["X-Awardee-Event"]

    inserted = await db.execute(
        """
        INSERT INTO webhook_deliveries_seen (id, event_type)
        VALUES ($1, $2)
        ON CONFLICT (id) DO NOTHING
        """,
        delivery_id,
        event_type,
    )

    if inserted == "INSERT 0 0":
        return Response(status_code=200)

    payload = await request.json()
    await process_event(event_type, payload)
    return Response(status_code=200)

Insert the dedupe row in the same transaction as the side effects of processing the event. Otherwise a crash between the insert and the work will mark the delivery as seen without actually doing the work.

Pruning the table

The table grows by one row per unique delivery. A retention job that deletes rows older than ~30 days is sufficient — Awardee retries for at most 24 hours, so any id older than that will never be re-delivered. The remaining ~6 days of headroom catches manual replays from the dashboard.

DELETE FROM webhook_deliveries_seen WHERE received_at < now() - interval '30 days';

What about ordering?

Idempotency dedupes redelivery. It does not order out-of-order events. For ordering, see Retries and ordering — the short version is: compare the timestamp inside the payload to whatever your downstream store has, and skip stale updates.

Get started

Identity

Concepts

Webhooks

Chatbots

Customers

Articles

Article Categories

Article Tags

Knowledge Bases

Conversations

Conversation Tags

Submissions

Pages

QR Codes

QR Groups

Products

Objects

Custom Domains

Custom Domain Routes

Team

The dedupe key

The pattern

Pruning the table

What about ordering?

​The dedupe key

​The pattern

​Pruning the table

​What about ordering?

The dedupe key

The pattern

Pruning the table

What about ordering?