Being told rather than asking.
WHAT A WEBHOOK IS
A request the service makes to an address you provide, when something happens.
WHAT IT REPLACES
Polling repeatedly to check for changes.
WHY THAT MATTERS
Polling wastes requests and adds delay.
WHAT THE RECEIVER MUST HANDLE
Verifying it genuinely came from the sender Responding quickly Duplicates Events arriving out of order Events arriving late
WHY VERIFICATION IS ESSENTIAL
The address is public, and anyone can send to it.
HOW IT IS USUALLY DONE
A signature over the body, using a shared secret.
WHAT TO CHECK
That the signature matches, computed over the raw body.
WHY THE RAW BODY
Parsing and re-serialising changes the bytes and breaks the signature.
WHAT TO DO ON RECEIPT
Acknowledge immediately, and process afterwards.
WHY
Senders time out, and a slow handler causes retries.
WHAT TO RETURN
A success status, quickly.
WHAT TO DO ABOUT DUPLICATES
Record event identifiers and ignore repeats.
WHY DUPLICATES ARE CERTAIN
Senders retry when unsure, which is correct behaviour.
WHAT TO DO ABOUT ORDERING
Never assume it; use the event's own timestamp or sequence.
WHAT TO LOG
Every event received, with its identifier.
