Webhook security
Verify event authenticity and freshness, bind events to local records, and handle duplicate or reordered webhook deliveries without repeated business effects.
What it means
Webhooks deliver events to an HTTP endpoint, often across organizational boundaries. Receivers need to verify who sent an event, prevent inappropriate replay, and process duplicate or reordered deliveries safely. A sender's destination validation is also important because outbound callbacks can create SSRF risks.
A practical example
A payment integration verifies the event signature over the expected raw payload, checks freshness according to the provider's specification, and records the event identifier. A repeat delivery acknowledges the existing result instead of shipping the same order again.
What to check
Follow the provider's signing protocol precisely, protect verification secrets, bind events to local records, and make processing idempotent. Test retries, signature failures, key rotation, and events arriving out of order.
A common pitfall
An event identifier alone is not authentication, and a valid signature does not guarantee that an event has not already been processed. These are separate checks.
Think it through
Why keep an event-processing record after successful verification?
Answer: Providers retry deliveries, so the receiver must distinguish a repeat event from a new business action.
Delivery is not a one-time transaction
Imagine a fictional academy receives a partner event confirming a learner's enrollment. The sender might retry because it did not receive a timely acknowledgment, even if the first event was already processed. Two deliveries should not create two enrollments or send conflicting confirmations.
Keep event receipt, verification, and business processing conceptually separate. A verified event can be recorded before a worker completes the action. This makes recovery and duplicate handling easier to reason about than performing everything without a durable status.
Verify exactly what was signed
Different providers define different signing formats, freshness rules, and rotation procedures. Use the provider's maintained specification and library where appropriate. Changing the payload representation before verification can conflict with a scheme that signs the original bytes.
A valid signature demonstrates the relevant authentication property under that scheme; it does not decide whether the event refers to the correct local account or is appropriate for the current state. Bind the event to known local records and permitted transitions.
Order and authority are separate questions
Suppose an enrollment update arrives before a related creation event because processing and delivery paths differ. The receiver should have a defined response rather than assuming arrival order is always business order.
The academy also needs a strategy for verification-key changes and unavailable downstream services. Logging should explain processing outcomes without exposing the shared verification secret or unnecessary learner data.
For a safe exercise, create three invented deliveries: a valid new event, an exact retry, and an older event arriving late. Write the expected verification and processing result for each. Add an invalid signature and explain why it is rejected before business effects occur. The exercise demonstrates that sender authentication, freshness, deduplication, and authorization are different decisions even when they happen within one endpoint.
Related concepts
References & further reading
Original explanations, with primary references for deeper study.
OWASP: Webhook Security