Technical
Webhook
Webhook is an HTTP POST that one service sends to a URL you provide when something happens, such as a payment succeeding. You get told instead of having to ask.
How it is measured
Your endpoint receives a JSON body and headers, often with a signature such as `X-Signature` computed from a shared secret. Count deliveries received against the sender's delivery log, and watch response codes. Senders usually treat any non-2xx response, or a timeout of 5 to 30 seconds, as a failure and retry.
Verify the signature over the raw body before parsing it, and store the event id so duplicates are ignored.
Worked example
A shop's payment provider posts `payment.succeeded` to `/hooks/pay`. The handler does full order fulfilment inline and takes 14 seconds. The provider times out at 10 and retries three times, creating 4 shipments for 1 order. Returning 200 at once, queueing the fulfilment, and checking the event id `evt_91c` fixes it.
The sender's dashboard shows 99.1% delivered. The missing 0.9% are the retries during the 40 minutes the endpoint threw 500s.
How it differs
A webhook is push: they call you. An API key is the credential you use when you call them. A webhook endpoint often also verifies a shared secret, which works like a key running in the other direction.
Common errors
Skipping signature checks. Doing slow work before responding. Not deduplicating. Assuming deliveries arrive in order. Exposing a guessable URL. Not logging the raw payload. Parsing before verifying.
In practice
Return 2xx fast, queue the work, verify signatures on the raw body, and deduplicate on the event id. Replay a few events from the sender's dashboard to test the handler.