Design privacy webhooks for retries, duplicates and missed events

A webhook is a notification path, not a guarantee that the receiving system has completed the requested work. That distinction matters when the event concerns a withdrawal, a correction or a deletion decision.

The receiving service needs to survive repeated delivery, uncertain responses and events arriving in an unexpected sequence. The sending service needs to know when work remains unresolved. Treat these as normal design conditions rather than unusual exceptions left for operations to repair.

Define the delivery contract

For each integration, document what an acknowledgement means, which events are subscribed to, how retries work and whether ordering is guaranteed.

Stripe’s webhook documentation, for example, describes duplicate events and non-guaranteed ordering. Those are properties of that documented service. They also illustrate why a privacy integration should inspect its own provider’s delivery contract instead of assuming one message produces one ordered action.

A hypothetical retailer connects a preference service to a messaging platform. The central service emits a withdrawal event, but the receiver’s response is lost after it has applied the change. A retry is appropriate only if processing the same instruction again does not create an incorrect additional effect.

Give the operation a stable identity

An event identifier can help recognise repeated delivery. The receiver should record enough state to distinguish a previously completed operation from a new one.

AWS’s guidance on idempotent APIs explains the use of a caller-supplied request identifier to represent intent and handle retries without additional side effects. It also highlights the need to coordinate recording that identifier with the operation being performed.

For the withdrawal example, avoid a sequence where the receiver marks the event complete and then fails before updating the preference. The reverse gap can also cause trouble if an action occurs but its completion record is lost.

Use the storage and transaction mechanisms appropriate to the system. Where a single transaction cannot cover a remote action, define a durable workflow and reconciliation process. An event table alone does not solve every distributed failure.

Do not let arrival order decide permission

Suppose an earlier opt-in notification arrives after a later withdrawal. Applying messages solely in arrival order could restore a permission that should remain withdrawn.

The integration needs a rule based on authoritative state, version or another reliable ordering mechanism. The right choice depends on the provider’s data model. A timestamp supplied by an untrusted caller is not automatically an authoritative sequence.

When an event is only a change notification, the receiver may need to fetch the current state through a scoped API. That read path requires its own authentication, authorisation and failure handling.

Record how conflicts are resolved. A reconciliation worker should use the same rule as the live receiver, or the two paths may undo each other’s work.

Verify origin before acting

A publicly reachable endpoint must establish that a notification comes from the expected source and is appropriate for the configured tenant. Follow the provider’s documented verification mechanism.

Stripe, for example, documents signature verification using the original request body. That is a specific implementation detail to follow when integrating with Stripe; another provider may have a different contract.

Do not log secrets, signatures or full personal-data payloads merely to debug verification failures. Keep useful error codes and restricted references. A verification error should not trigger an unverified fallback action.

Reconcile what notifications cannot prove

A durable queue helps decouple receipt from processing, but the service still needs visibility into failures and abandoned work. Distinguish received, processing, applied and confirmed states.

For the retailer, periodically compare the relevant central preference state with the messaging platform’s state using an authorised, minimised reconciliation path. Investigate mismatches instead of assuming that an old delivery success proves current agreement.

Test at least these conditions:

• The same event arrives more than once.
• The action succeeds but the response is lost.
• An older event arrives after a newer state.
• A receiver is unavailable and later recovers.
• A notification fails verification.
• An event is missed and reconciliation discovers the mismatch.

The acceptance result should show the final preference state and the evidence behind it. “Webhook returned success” is a transport observation. A reliable privacy workflow also establishes whether the intended change reached the system that acts on it.