Webhook providers retry. Events can arrive late, twice, or in an unexpected order. Returning 200 quickly is not the same as keeping subscription state correct.
Authenticate before parsing deeply#
Compare the provider authorization value using constant-time comparison where appropriate. Reject the request before performing expensive work, and never log the secret or full payload.
Signature-based providers may also require the raw request bytes and a timestamp tolerance. Follow the provider's exact verification contract.
Persist the event identity#
insert into provider_events (id, event_type, received_at, raw_event)
values ($1, $2, now(), $3)
on conflict (id) do nothing;
The provider's event ID becomes the deduplication key. If the insert reports an existing event, return success without repeating the business effect.
Storing the raw event can support audits and replay, but it may contain personal data. Apply retention, access controls, and encryption appropriate to its sensitivity.
Resolve the internal subject carefully#
Providers may send current IDs, original IDs, and aliases. Validate each candidate before associating it with an internal user. An unrecognized identifier should be recorded for reconciliation rather than guessed.
Make state transitions idempotent#
Upsert entitlement state using event timestamps or provider sequence information. A delayed cancellation must not overwrite a newer renewal simply because it arrived later.
For uncertain state, query the provider's current subscriber API and reconcile. Webhooks signal change; the provider's read API can serve as the authoritative repair path.
Keep analytics idempotent too#
Use the webhook event ID as the analytics insertion ID. Database deduplication is incomplete if every retry still records another purchase event.
Test duplicate delivery, invalid authentication, unknown users, out-of-order events, provider timeouts, and replay after partial failure. Reliable webhook handling assumes the transport is at least once and builds exactly-one-business-effect behavior on top.