Skip to content
ITEMRA
Documentation menu

Developers

Webhooks (developer)

Receiving Itemra webhooks correctly: headers, HMAC verification, idempotent consumption, retries, and replay.

The delivery

Subscriptions are managed in Settings → Webhooks or via /v1/webhooks. Each delivery POSTs the standard envelope (see the events feed — same shape, same catalog) with these headers:

X-Itemra-Webhook-Id: evt_01…
X-Itemra-Webhook-Delivery-Id: whdel_01…
X-Itemra-Webhook-Event: stock.changed
X-Itemra-Webhook-Timestamp: 1783937730
X-Itemra-Webhook-Signature: v1=<lowercase-hex-hmac>

Verify before you trust

  1. Read the exact raw UTF-8 body before any JSON parsing.
  2. Reject timestamps outside a five-minute replay window.
  3. Concatenate <unix-timestamp>.<raw-body> — no reformatting.
  4. Compute HMAC-SHA256 with the subscription's signing secret.
  5. Compare against v1=<hex digest> in constant time.
  6. Record X-Itemra-Webhook-Id; return 2xx for an id you've already processed.

The secret is revealed once at creation/rotation — store it in a secret manager and never log it. Rotation applies to deliveries created after it; in-flight retries keep the secret they were issued with.

Consume idempotently, respond fast

Delivery is at-least-once: duplicates are normal, ordering is not guaranteed — dedupe on the event id, use occurredAt for domain time, and fetch the current state from the API when order matters. Return 2xx quickly and process asynchronously; slow receivers get retried into backoff.

Retries, dead letters, replay

Non-2xx, timeouts, and network errors retry with capped exponential backoff; exhausted deliveries dead-letter and stay visible in the delivery log, where replay re-sends them after your receiver is fixed. Test deliveries run the same signing and worker path as production events — use them to verify the whole chain before going live, and alert on dead letters in production.