Back to all articlesWebhook processing

Choose When to Acknowledge a Webhook Receipt

Alactic Editorial10 min read

Prepared with AI assistance by Alactic Editorial. Examples identified as hypothetical are illustrative, not customer results.

A webhook arrives, your endpoint returns success, and the process stops before saving the event. The sender may now consider its job finished, while your team has no recoverable work item. Move the response to the other extreme—after every business operation—and a slow dependency can leave the sender waiting even though your system already has the event.

The recommended default is to acknowledge a valid webhook after it crosses a durable acceptance boundary: the point at which your system has committed enough information to recover and process it without relying on another delivery. Business processing can then finish separately. If persistence fails or its outcome is uncertain, do not claim durable acceptance until you can establish it.

The exact response code, response body, deadline, and consequences of a missing or unsuccessful response depend on the sender’s documented contract. The architecture below helps you decide what your response should mean; it does not substitute for that contract.

1. Decide what a successful receipt promises

Write the promise before choosing where to return a response. A useful internal definition is: “We have accepted responsibility for this event and can recover the remaining work after a process restart.” That is narrower than “the business action succeeded” and stronger than “the request reached our server.”

These distinctions matter to operations. A receipt response should not cause a dashboard to mark an order updated, a customer notified, or a workflow completed unless those actions have actually finished. Equally, a downstream outage should not erase the fact that an event was safely received.

Separate at least these concepts:

  • Received: request bytes reached the endpoint. This alone is not durable acceptance.
  • Accepted: a recoverable event record or work item has been durably committed.
  • Processing: a worker has begun the business operation.
  • Completed: the defined business outcome has been confirmed.
  • Needs attention: processing cannot proceed automatically under the current recovery policy.

For sources that require synchronous business completion in their response, this asynchronous acceptance pattern may not fit. Identify that exception explicitly rather than assuming every webhook is a notification that can be processed later.

2. Put the boundary after recoverable storage

A durable acceptance boundary is a property of the whole recovery path, not simply the presence of a database call. Before acknowledging, ask whether a fresh worker could discover the event, understand what it represents, and resume the required work after the receiving process disappears.

A recommended receipt record includes the source identity, the destination workspace or account, a reliable event identity where available, the payload or a durable reference to it, receipt time, and processing state. Store the metadata needed to interpret the event, such as its declared type or version. Apply appropriate access controls and retention rules rather than retaining sensitive request data indefinitely.

Keep validation focused on what acceptance requires. Check authenticity according to the sender’s documented mechanism, establish the intended destination, and determine whether the event can be safely recorded. Slow enrichment and unrelated business lookups usually belong after acceptance. An invalid request needs a separate rejection policy; it should not be treated as a temporary storage outage.

Two common designs can provide the boundary:

  • A durable inbox: commit an event record that workers scan or claim for processing. The record itself is the recoverable work item.
  • A durable queue: acknowledge only after the queue confirms acceptance under its documented durability semantics. Ensure the queued data is sufficient for recovery, including any referenced payload.

A memory buffer, a started background task, or a log line is not an adequate boundary unless it is deliberately backed by a durable recovery mechanism. Similarly, invoking a queue client is not the same as receiving a successful persistence confirmation.

3. Use a filled receipt-state table

Fictional worked example: a service receives account-change events, saves each event in an inbox, and lets a worker update an internal customer record. The inbox also contains the worker’s recovery state. In this hypothetical design, the sender’s contract recognizes a configured successful receipt response and documents its treatment of temporary failures. Exact codes and timing remain contract-specific.

The following filled table is a decision artifact for that fictional service. “Success” means the sender’s documented successful receipt response, not a claim that business processing has finished.

Receipt state          | Durable evidence                 | Response choice             | Recovery owner
-----------------------|----------------------------------|-----------------------------|---------------------------
New event stored       | Committed inbox row; pending     | Return receipt success      | Internal worker
Storage failed         | No committed inbox row           | Do not return success; use  | Sender retry if supported;
                       |                                  | documented failure behavior | receiver alerts/reconciles
Duplicate received     | Matching committed receipt found | Return receipt success;    | Existing internal job
                       |                                  | do not create another job   |
Downstream work failed | Receipt committed; retry state   | Receipt remains successful | Internal retry or review
                       | saved with failure details       |                             |
Storage outcome unknown| Commit confirmation lost; record | Resolve by event identity; | Receiver investigates;
                       | not yet confirmed                | no unverified success       | duplicate handling protects

For the duplicate row, “matching” means more than finding a familiar identifier. The service checks the relevant source and destination scope and confirms that the stored record represents the same event. An identity collision or materially different payload requires investigation, not silent dismissal.

For the downstream-failure row, the receipt response has normally already been sent. There is no later response that retracts it. The accepted event remains the receiver’s responsibility, so worker failures must be visible in internal state and recovery queues.

Use this table during incident reviews. If an event disappears, the first question becomes concrete: which row described the event when the endpoint responded, and what durable evidence supported that choice?

4. Close the gaps between saving and scheduling

A frequent weakness sits between two individually reasonable steps: save the event, then publish a job. If the save succeeds but job publication fails, the endpoint may have a receipt record that no worker will ever discover.

There are several ways to close this gap. Workers can scan the durable inbox directly. Alternatively, a database transaction can save both the receipt and an outgoing work record; a separate publisher then retries sending that work record. This is often called an outbox pattern. It still needs monitoring and duplicate-safe consumption, but it avoids depending on one uninterrupted sequence of separate writes.

Do not acknowledge solely because the first write succeeded if the event remains stranded without a recovery path. The key test is not “was something saved?” but “can unfinished work be found and resumed?”

There is also a gap after storage commits but before the sender receives the response. A connection can fail during that interval. The receiver may have accepted the event while the sender remains uncertain. Design for another delivery to encounter the existing receipt safely rather than trying to eliminate all such uncertainty through response timing.

5. Make duplicates safe without suppressing unfinished work

Duplicate receipt handling and business-action idempotency solve related but different problems. Receipt deduplication prevents repeated deliveries from creating multiple independent jobs. Business-action idempotency protects against a worker repeating an operation after a timeout or restart.

Use the sender’s documented event identity where suitable, scoped to the relevant source and destination. Enforce uniqueness through a concurrency-safe storage mechanism rather than a separate “check, then insert” sequence that competing requests can both pass. Do not assume a payload hash is a reliable event identity: distinct events may carry identical data, and equivalent events may have different representations.

On a duplicate, inspect the existing record:

  • Pending or running: return the appropriate receipt success without creating a second independent job.
  • Completed: acknowledge the existing receipt without repeating its business effects.
  • Failed or awaiting review: preserve the recovery state. A duplicate is not proof that the problem has been fixed.

Choose a deduplication retention period with the source’s redelivery and replay behavior in mind. If identity records expire before old events can return, those events may look new. Document what happens then, including how business-action safeguards limit repeated effects.

6. Treat failed and uncertain persistence differently

A definite storage failure means you have not accepted durable responsibility. Return the contract-appropriate failure response, or follow its documented timeout behavior, rather than sending success to keep the endpoint looking healthy. Do not assume every non-success response triggers a retry, or that retries continue indefinitely.

An uncertain storage outcome requires a different approach. A database timeout can leave the receiver unsure whether the write committed. Where practical within the response budget, look up the event using its stable identity. If a matching durable record exists, use it. If the outcome cannot be established, avoid claiming confirmed acceptance and make a subsequent delivery safe through uniqueness checks.

Do not select a status merely because its name sounds useful. A rate-limit response, a server-failure response, and a request-rejection response can have different meanings to different senders. Verify the documented behavior before making any one of them part of your recovery design.

If the source offers no dependable redelivery mechanism, unsuccessful acceptance needs another recovery path: reconciliation against a source record, a supported replay mechanism, or an operational escalation. Where no recovery facility exists, document that limitation and alert on acceptance failures. A failed response alone does not restore lost work.

7. Keep downstream failure inside the processing system

Once durable acceptance succeeds, downstream recovery belongs to your processing architecture. Keep attempt history, the latest failure category, the next eligible attempt, and enough context for an operator to understand the blocked action.

Separate temporary failures from events that require a decision. A temporarily unavailable dependency may justify a delayed retry. An unsupported event version or an unresolved destination mismatch may need review instead. Use bounded retry policies and an explicit terminal or review state rather than leaving events in an endless loop.

Business side effects need special care. If an external action succeeds but the worker crashes before recording completion, another attempt may repeat it. Where supported, use a stable operation key or query the external result before retrying. Where neither is possible, document the ambiguity and decide when human review is safer than automatic repetition.

A receipt acknowledgement is also not permission to perform every possible downstream action. Processing must still respect the applicable authorization and business rules. Durable storage preserves the event; it does not override those rules or establish that an action is appropriate.

8. Verify the boundary with failure tests and observable outcomes

Start by reviewing the source contract: what counts as success, how quickly a response is required, which failures lead to redelivery, how event identities behave, and what replay facilities exist. Then test the implementation around the chosen boundary rather than testing only the happy path.

Hypothetical test set: stop the receiver before storage, after commit but before response, and after acknowledgement but before worker execution. Also simulate storage timeouts, simultaneous duplicate deliveries, and a downstream action that succeeds just before its worker loses confirmation.

For each test, record whether the event remains recoverable, whether a duplicate creates extra work, and who owns the next recovery step. An expected result should be specific: “the committed inbox row remains pending and is claimed after restart,” not simply “the system handles failure.”

Measure acceptance separately from processing:

  • Receipt health: confirmed durable acceptances, storage failures, uncertain commits, and response latency against the sender’s deadline.
  • Processing health: pending backlog, oldest uncompleted event, completion delay, and events awaiting review.
  • Recovery health: duplicate receipts, recovered stranded work, and suspected repeated side effects.

A fast receipt endpoint can coexist with a stalled worker backlog. Reporting both prevents acceptance success from concealing business failure.

Your next action is to complete a receipt-state table for one live event type and trace every successful response path to its durable evidence. Run the failure tests, record the observed states, and assign an owner to each recovery path. The boundary is ready when a process can stop immediately after acknowledgement and the accepted work is still discoverable, recoverable, and visibly unfinished until it actually completes.

WebhooksReliabilityEvent processingSystem design

Put the next conversation to work.

Explore Alactic Communications for WhatsApp conversations, campaigns and AI-assisted workflows. Choose the product and plan that fit your team.

Explore Communications