Find the missing event before replaying the webhook
Diagnose missing webhook events from source and processing evidence, then recover only unresolved work within a defined replay scope.
CharityStack
·4 min read
Donation webhook delivery failures need evidence before a replay. Confirm the source event, inspect its attempts at the intended destination, and compare those attempts with your integration's processing record. Retry only the unresolved work after the failure is fixed and duplicate protection is verified.
An absent downstream gift does not tell you whether the provider failed to deliver, your endpoint rejected the event, or a worker failed after acceptance. Those paths need different next actions.
Start with a bounded missing record
Collect the payment or source record identifier, the expected event type, account, environment, and approximate time with timezone. Write the expected downstream result and the place you looked for it.
Do not use the donor's email address alone to locate the event. One donor can have several gifts, and a payment may produce several event types. Use identifiers from the actual source transaction whenever available.
Assign an incident owner who can coordinate with the technical maintainer. The operator's job is to identify the missing business result and supply evidence; the maintainer's job is to inspect delivery and processing safely.
Compare delivery with processing
Stripe's delivery troubleshooting guidance directs users to inspect failed events, delivery attempts, HTTP status codes, and response details. Other providers have their own tools and retention windows, so use the documentation for the system actually sending your events.
Make the maintainer answer three questions:
- Does the event exist in the correct source account and environment?
- Was it attempted at the intended endpoint, and what did that endpoint return?
- Was it durably accepted and processed into the expected downstream result?
If no source event exists, check the expected event subscription and source action. If delivery failed, use the response evidence to investigate the endpoint. If delivery succeeded but processing failed, inspect the internal queue or worker trail rather than treating another provider send as the only remedy.
A successful HTTP response demonstrates endpoint acceptance, not the final CRM or donor record. Keep the event identifier attached to processing evidence so your team can follow it across systems.
Fix the failing stage before retrying
Have the maintainer classify the observed failure: unreachable destination, rejected request, signature mismatch, timeout, or internal processing error. Capture the time and error category without copying signing secrets, credentials, or complete donor payloads into a support message.
Confirm the correction in a controlled environment where possible. If the destination URL or signing configuration changed, verify that the source is sending to the intended endpoint and that the receiver expects the matching account and environment.
For internal worker errors, repair the processing logic or blocked dependency before retrying its work. A replay through the same unresolved defect can create another failed attempt without resolving the donor's missing record.
Build the replay list from evidence
Choose the smallest useful scope: a known event, a documented outage window, or a specific event type at one destination. Compare every candidate with the processing record before marking it for recovery.
Stripe's undelivered-event guide warns that manual processing can overlap with automatic retries and describes skipping work already processing or completed. Its unsuccessful-delivery filter covers failure at at least one endpoint, so it is not a list of everything missing from your particular destination.
Ask the technical owner to verify duplicate processing protection for the path being replayed. Import controls and webhook controls are implemented differently; the shared operating requirement is that the same intended gift does not become another gift.
List expected side effects before recovery. A replay might affect a gift record, a receipt workflow, a subscription state, or a CRM action. Do not perform an uncontrolled replay if you cannot explain how those effects are handled.
Close with the business result
Recover a small, known item first and inspect its downstream result. Then proceed through the approved bounded list, recording which items completed, which were already resolved, and which still need investigation.
Check actual gift identity and destination state against the CRM record mapping. Do not create another donor record as a shortcut for a missing update. If the payment succeeded, asking the donor to pay again is not a recovery plan for the integration.
Keep the incident note with the source identifiers, failure window, correction, replay scope, and final exception list. The workflow is finished when the missing business result is verified and unresolved items have an owner, not merely when the provider dashboard shows a successful delivery.