A webhook is an external request to a privileged endpoint Payment, CRM, and messaging providers call application endpoints to report events. The endpoint m...
A webhook is an external request to a privileged endpoint
Payment, CRM, and messaging providers call application endpoints to report events. The endpoint may update an invoice or grant account access, so a successful POST must prove more than that it reached the server. Validate the provider's signature, constrain the accepted event types, and process each event idempotently.
The exact signature method differs by provider. Follow its current official SDK and documentation rather than writing a generic HMAC check copied from another service.
Verify the raw payload
Many providers sign the exact request body. JSON decoding and encoding the body again may change whitespace or key order and break verification. Read the raw body, the signature header, and the configured endpoint secret, then call the provider's verification method before trusting any event fields.
Set a timestamp tolerance if the provider supports one. Reject missing or invalid signatures with an appropriate non-success response. Keep signing secrets in environment backed configuration and rotate them through the provider's supported procedure.
Persist before processing
Store the provider event ID under a unique constraint, along with its type, received time, processing state, and a minimal payload or secure reference. A duplicate delivery should return success after confirming the event was already accepted, rather than applying the business action again.
If processing can be slow, queue a job after saving the event. The job should reload the event record and use an atomic transition so two workers cannot perform the side effect concurrently. For financial events, reconcile against the provider's authoritative object state when event ordering is ambiguous.
Keep the event handler narrow
Map each accepted event type to an explicit operation. Ignore unknown event types safely and log the type for investigation. Do not grant entitlements based solely on a checkout success page or an unverified request body. The browser redirect and webhook can arrive in either order.
For a subscription, model renewal, failure, cancellation, and recovery separately. For an order, protect fulfillment with a unique operation key so retries cannot ship or bill twice.
Test replay and outage behavior
Send the same signed event twice and assert one business transition. Send an invalid signature and assert zero writes. Simulate an exception after event persistence, retry the job, and verify it completes once. Test out of order events and a provider outage. Use the provider's test mode to confirm real signatures and payload shapes in addition to local mocks.
Common mistakes
- Parsing and reserializing JSON before signature verification.
- Accepting a browser supplied status as payment proof.
- Deduplicating in memory instead of a durable unique index.
- Returning success before the event is durably stored.
- Logging secrets or full sensitive payloads.
Conclusion
A webhook endpoint is a small integration boundary with outsized consequences. Verify authenticity, persist an event ID, handle retries, and reconcile uncertain state. This pattern supports the web and SaaS development work around billing and integrations.
References