Webhooks let another service notify an application about payments, identity events, or other changes. They are convenient, but delivery is usually outside the application's control. A provider may retry, send events out of order, or deliver a message after a temporary outage. A reliable consumer authenticates the event, records it safely, and applies business changes idempotently. It treats the webhook as a signal to verify, not as an unquestionable command.
Verify the sender and payload
Use the provider's signature scheme with its documented raw-body requirements. A parsed and reserialized body may not verify against the original signature. Check the timestamp or replay window when provided and rotate signing secrets through a planned process. Limit payload size and validate the event type and required fields. IP allowlists can be an additional signal but are not a substitute for cryptographic verification when supported. Keep secrets out of logs and public error responses. An unauthenticated caller must not be able to mark an order paid by posting a plausible JSON document.
Acknowledge quickly, process safely
Some providers retry if the endpoint does not respond promptly. Record the verified event and return an acknowledgment after durable acceptance, then process complex work asynchronously if appropriate. Do not acknowledge an event that was not stored when losing it would harm customers. Separate transport errors from business failures so a provider retry does not repeatedly execute a side effect. A queue or event table gives operators visibility into pending, completed, and failed work. Keep the design simple enough for the product's expected event volume.
Make handlers idempotent
Use the provider's event ID or a stable logical key to detect duplicate deliveries. Reserve and complete processing atomically where possible. A duplicate payment-success event should return the same outcome without issuing another invoice or notification. If processing fails halfway, a retry must know which steps completed. Business state transitions should validate the current state rather than blindly overwrite it. Record event ID, tenant, resource, and outcome for investigation. A duplicate is normal webhook behavior, not necessarily an attack.
Handle ordering and reconciliation
A refund event may arrive before a delayed payment event, or a subscription update may arrive after a cancellation. Do not assume arrival order matches business order. Use provider timestamps and current authoritative state carefully, and fetch the current object from the provider when an event is ambiguous. Schedule reconciliation for critical flows so a missed webhook does not leave an order permanently wrong. Define what happens when an event references an unknown tenant or resource; do not attach it to a default account.
Observe and test failures
Monitor failed signatures, queue age, repeated retries, and reconciliation differences. Keep enough payload metadata to diagnose problems without retaining unnecessary personal data. Test duplicate events, out-of-order events, timeouts, secret rotation, and a crash after an external side effect. Use the provider's test tools where available, but also exercise the application handler independently. A support view should show the status of a specific event and a safe way to retry it without changing its tenant scope.
Keep the boundary clear
The webhook endpoint translates an external event into an application operation. The business part still owns the rule for changing an order, user, or subscription. For SMB SaaS, a small durable inbox and idempotent handler can provide dependable integration without a complex event platform. The result is a service that remains correct when the provider behaves as real networks do: with duplicates, delays, and occasional failures. Review the provider's retention window and decide how long the application must keep event IDs for deduplication. Test a late retry after that window if it could create a financial or access change. A clear replay policy is part of the integration contract.