Idempotency - hooksnode

On the way in

Send the X-Idempotency-Key header with each event. hooksnode stores the first event with a key. When the same key comes again to the same project, hooksnode stores nothing and answers:

{ "status": "duplicate — already accepted" }

The status is 200, so your sender does not retry.

curl -X POST https://hooksnode.com/p/<source-id> \
  -H "X-Idempotency-Key: order_9311_paid" \
  -d '{"event":"order.paid","order_id":"9311"}'

Keys are unique for each project.
A key can be up to 255 characters.
Use an ID that your system already has, such as the provider’s event ID.

hooksnode sets keys for you on other sources:

Source	Key
WhatsApp	A hash of the body, so Meta’s retries are stored once.
Gmail	`gmail:<source>:<message>`
Outlook	`outlook:<source>:<message>`
IMAP, Watch a URL	`poll:<source>:…`
Bank alerts	The email’s key plus `:bank`

On the way out

hooksnode delivers at least once. Your endpoint can get the same event twice. Make your handler safe to run twice:

Find a stable ID in the event. For example, Paystack’s data.reference, the email’s message.id, or the bank event’s email.id.
Before you do the work, check if you already did it for that ID.
Store the ID in the same database transaction as the work.

INSERT INTO processed_events (event_id) VALUES ($1)
ON CONFLICT (event_id) DO NOTHING
RETURNING event_id;
-- No row back: you already handled it. Answer 200 and stop.