Glossary

webhook-id

webhook-id is the delivery header that carries an event id. Receivers dedupe on it so a retried delivery is not processed twice.

Updated November 12, 2026

At OneLifeVibe

Related terms

What it means

webhook-id is an HTTP header on a webhook POST. Its value is the id of the event being delivered, not an id for that particular request. When the same event is sent again, the header carries the same value, which gives your receiver a stable key for spotting a repeat.

That matters because webhook delivery is often at-least-once. The sender may retry after a timeout, a dropped connection or a non-2xx response, even when your handler already did the work. Deduping on webhook-id turns those repeats into no-ops and makes the handler idempotent: processing the same event twice leaves the same result as processing it once.

Treat the value as an opaque string. Store it, compare it, and do not parse it for meaning.

How it works

A delivery arrives as a POST with three related headers. webhook-id is the event id. webhook-timestamp is Unix seconds. webhook-signature starts with v1= and holds the hex HMAC-SHA256, keyed with the endpoint secret, of {timestamp}.{raw body}. Here timestamp is the webhook-timestamp value and raw body is the exact bytes you received.

Verify before you trust the payload. Read the raw body, not a parsed object. Rebuild the signed string, compute the HMAC with the endpoint secret and compare it to the value after v1=. Reject a delivery whose webhook-timestamp is more than 5 minutes (300 seconds) from your clock.

Then check webhook-id against your dedupe store. If you have seen it, return 2xx and stop. If not, record it, do the work and return 2xx quickly. Anything other than 2xx counts as a failure and is retried, so a handler that times out will produce another delivery with the same webhook-id.

How OneLifeVibe uses it

Every OneLifeVibe delivery is a POST with webhook-id, webhook-timestamp and webhook-signature, plus x-olv-event and x-olv-world. The endpoint secret used for the signature is returned once, when the subscription is created, so store it then.

Delivery is at-least-once. Dedupe on the webhook-id header, which is the event id. Return a 2xx quickly; anything else is treated as a failure and retried.

Use x-olv-event to route by event type and x-olv-world to see which world the event belongs to. Both arrive alongside webhook-id, so you can verify, dedupe and then route.

Common mistakes

Deduping on a body hash, on webhook-timestamp or on x-olv-event. Events can share a type, and a timestamp is not unique to an event. The stable key is webhook-id.

Parsing the body before checking webhook-signature. Read the raw bytes, verify, then parse. Returning 4xx for a duplicate is another mistake: a duplicate is not an error, so return 2xx and let the sender stop.

Doing slow work before responding, or writing the dedupe record after the side effect. Record webhook-id and apply the change in the same transaction where you can, then return 2xx.

Questions

Should I dedupe on webhook-id or on the event payload?

webhook-id. It is the event id and stays the same across retries, while the payload is just data. Store the ids you have processed and check each new delivery against them.

What counts as a successful OneLifeVibe webhook response?

Any 2xx response. Anything else is a failure and is retried, so return 2xx as soon as you have verified the signature and recorded the webhook-id.

See it working. The OneLifeVibe connector and Platform API put these pieces together.

Get a free key Read the docs

Written from the OneLifeVibe tool registry and platform configuration, and checked automatically before publishing. Something wrong? Tell us.