What is idempotency?
An operation is idempotent if performing it multiple times produces the same result as performing it once. DELETE /users/42 is idempotent — deleting twice doesn't change the outcome. POST /charges is not — each POST creates a new charge.
Idempotency matters in webhook systems because duplicates always arrive. The provider retries on slow responses; the delivery layer retries on failures; replays re-fire successful deliveries. Without idempotency, every duplicate produces an unwanted side effect: a double charge, a duplicate user, a doubled email.
How to make non-idempotent operations safe
The standard pattern is an idempotency key — a unique value attached to each request. The receiver records the key and refuses to re-process the same one twice.
In HTTP, the convention is the Idempotency-Key header. The sender generates the key; the receiver stores it with the response; future requests with the same key return the previous response without re-running.
For webhooks specifically:
- Inbound (your handler): dedupe on the provider's event ID (
event.idfor Stripe,X-GitHub-Deliveryfor GitHub,svix-idfor Standard Webhooks). - Outbound (your sender): include an idempotency key so your customer's handler can dedupe.
Hooksbase honors the Idempotency-Key header on every ingest call, and forwards a unique webhook-id header on every dispatch (Standard Webhooks-compatible).
For the deeper guide: The complete guide to idempotency keys.
Frequently asked questions
Why do webhook systems need idempotency?
Because duplicates always arrive. The provider retries on slow responses, the delivery layer retries on failures, and replays re-fire deliveries that already succeeded. Without idempotency each duplicate produces a real side effect — a double charge, a duplicate user, a second email.
How do you make a non-idempotent operation safe?
Attach an idempotency key. The receiver records the key with its response and returns that stored response instead of re-running the operation. In HTTP the convention is the Idempotency-Key header.
What should a webhook handler deduplicate on?
The provider's own event ID: event.id for Stripe, X-GitHub-Delivery for GitHub, svix-id for Standard Webhooks. Hooksbase honors the Idempotency-Key header on ingest and sends a unique webhook-id header on every dispatch.
What is Hooksbase?
Hooksbase is event infrastructure for AI agents. It ingests events over four channels — HTTP, email, HTML form, and scheduled cron — verifies them, routes them by rule, runs versioned Automations in the event path, and delivers them to HTTP and cloud destinations (AWS SQS, AWS EventBridge, GCP Pub/Sub, and S3-compatible storage) with retries, strict ordering, Standard Webhooks-compatible signing, deterministic replay, and a dead-letter path. It is a hosted service, runs on Cloudflare Workers, is operated at hooksbase.com, and is not affiliated with — and shares no code or ownership with — other similarly named webhook, hook, or tunnelling tools.
Related terms
- Webhook
An HTTP request one service sends to another to notify it that something happened.
Read - Retry
Re-attempting a failed delivery on a backoff schedule until it succeeds or hits a retry budget.
Read - Replay
Re-running a retained event with the same input — typically after fixing a bug that caused the original to fail.
Read - Inbound email parsing
Converting a raw RFC-822 message into structured fields a consumer can read.
Read