Back to all articlesWebhook processing

Handle Webhook Events That Arrive Before Their Required Context

Alactic Editorial10 min read

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

A webhook references a customer record that your system has not stored yet. Rejecting it immediately may discard a valid change; applying it anyway may attach activity to the wrong record or trigger an action without enough context. When a webhook event arrives before its related record, treat the missing prerequisite as a dependency to resolve, not automatically as an invalid event.

The practical choice is to hold the event durably, retrieve context only through a documented and authorised source capability, retry a plausibly temporary failure, or escalate an unresolved dependency. Every hold needs an owner, a next check, and a deadline. Otherwise, a retry queue becomes a place where business work disappears.

The workflow below is a recommended design, not a claim that any particular product provides these controls. The fictional worked example and filled worksheet show how to make the decision explicit without inventing a source system's retrieval capabilities.

1. Identify the prerequisite before choosing a response

Start by writing down exactly what prevents safe application. “Customer missing” is less useful than “the referenced customer is absent from this workspace's local store.” Similarly, “version conflict” does not explain whether you need an earlier state, an ordering guarantee, or a corrected event.

Separate these dependency types:

  • Missing parent: The event refers to a record that has not arrived or has not finished processing.
  • Missing prior version: Applying a change requires a specific earlier state, not merely the latest record.
  • Deleted reference: The prerequisite existed but has been removed. Waiting may never make it available again.
  • Unknown cause: Available evidence cannot yet distinguish delayed arrival, an incorrect identifier, deletion, or an access problem.

Also ask whether the dependency is truly required. An activity might be safely retained as an unapplied event without linking it to a customer. That does not mean it is safe to include it in customer totals or use it to send a message. Define what “applied” means for each event type, including any downstream effects.

Do not create a placeholder parent merely to satisfy a database constraint unless your application explicitly supports incomplete records and prevents them from being treated as authoritative. A placeholder can conceal the missing dependency rather than resolve it.

2. Separate receipt from successful application

Use distinct internal states for receiving an event and applying its business change. A useful design includes received, waiting_for_dependency, ready, applied, and review_required. Add a resolved-without-application outcome when an operator intentionally closes a case without changing business records.

Persist enough information to resume work: the event identity, source, workspace boundary, payload or secure payload reference, receipt time, dependency key, and current processing state. Keep attempt history separate from the event's identity so a retry does not become a new business action.

The response sent to the webhook producer must follow that producer's documented delivery contract. If the contract permits acknowledging receipt after durable acceptance, internal processing can remain on hold. If persistence fails, do not report successful acceptance merely because the request reached your service. Nor should you choose a response code on the assumption that every producer retries it identically.

Before implementation, document this distinction in operational language: “Accepted” means the event is safely retained; “applied” means its authorised business change has completed. Support teams should not have to infer the difference from a generic success indicator.

3. Use a decision path that distinguishes evidence from guesses

  1. Check local evidence. Look for the exact dependency within the correct workspace, pending ingestion work, and any available deletion or version history. Do not match a missing identifier to a similar name.
  2. Assess documented retrieval. Confirm whether the source exposes the required object or historical state, whether your integration is authorised to access it, and what the response actually represents.
  3. Hold for a plausible arrival. If an earlier event is pending locally, a hold may be preferable to another source request. Record what evidence supports waiting.
  4. Retry a temporary obstacle. Retry a failed lookup or local application only when another attempt could change the outcome. Use a bounded schedule rather than an immediate loop.
  5. Escalate a permanent or unresolved obstacle. Confirmed deletion, unavailable history, exhausted lookup budgets, and expired holds need explicit dispositions.

Holding and retrying are not interchangeable. A hold represents unresolved business context. A retry is an attempt to perform a particular operation again. A held event may await a dependency-arrival notification without making repeated network calls.

A lookup also needs object-level authorisation. Knowing the referenced identifier is not enough to justify accessing the object. The OWASP guidance on object-level authorisation supports checking access to each requested object. Do not broaden credentials or search another workspace to make a dependency resolve.

4. Filled hypothetical dependency worksheet

Fictional worked example: A business application receives activity and record-change events from a fictional source. All identifiers, times, limits, and capabilities in this example are hypothetical. The source documentation in this scenario allows retrieval of current parent records but does not offer historical versions. These assumptions must not be transferred to a real integration without verification.

The hypothetical operating policy allows up to three remote lookup attempts per dependency, with checks after one, five, and fifteen minutes when appropriate. Each held event has a thirty-minute review deadline. A source-imposed wait can postpone a lookup, but cannot silently extend the review deadline. Dependency-arrival signals may prompt an earlier local check.

Worksheet entry A: Missing parent record

  • Event and prerequisite: Activity activity-A references parent customer-A in workspace workspace-A.
  • Evidence: The parent is absent locally. Its creation event is already durably queued but has not completed.
  • Decision: Hold the activity and prioritise checking the queued parent's processing outcome. Do not fetch immediately merely because retrieval is possible.
  • Release condition: The correct parent becomes available locally and passes the application's normal applicability checks.
  • Limits and owner: The ingestion worker rechecks after one minute and on a parent-arrival signal. The integration operator owns review at thirty minutes.
  • Hypothetical outcome: The parent is stored after four minutes. The activity is revalidated and applied once; its waiting interval remains in the audit history.

Worksheet entry B: Unavailable prior version

  • Event and prerequisite: Change change-B requires local version v7, but the local record is at v5.
  • Evidence: The change contains a delta, not a complete replacement. The documented lookup returns current state only; historical retrieval is unavailable.
  • Decision: Hold while checking retained events for the missing transitions. Do not use a current snapshot as if it were version v7.
  • Release condition: The exact required predecessor state is reconstructed from trustworthy retained events, or an authorised reconciliation procedure explicitly supersedes the delta.
  • Limits and owner: No historical API retries are scheduled because that capability does not exist. A data operations reviewer receives the case by the thirty-minute deadline.
  • Hypothetical outcome: The missing transitions cannot be found. The reviewer opens a reconciliation task; the original event remains unapplied with its reason recorded.

Worksheet entry C: Deleted reference

  • Event and prerequisite: Activity activity-C references customer-C.
  • Evidence: A retained deletion marker identifies that exact parent within the same workspace. A missing-record response alone would not establish deletion.
  • Decision: Stop parent-arrival retries. Retain the activity as an exception, subject to the application's retention rules, without recreating the parent.
  • Release condition: None through ordinary retry. A reviewer must choose an explicitly supported historical-linking or closure outcome.
  • Limits and owner: Route directly to the record-lifecycle owner rather than waiting for the hold deadline.
  • Hypothetical outcome: The owner closes the event without application because the activity has no valid destination. The deletion evidence and closure reason remain linked to the case.

Worksheet entry D: Unresolved hold with a review deadline

  • Event and prerequisite: Activity activity-D references customer-D, absent from local records and pending ingestion.
  • Evidence: A documented current-record lookup is authorised. The first request is rate-limited; a later permitted request returns no usable context. Neither response establishes permanent deletion.
  • Decision: Keep the activity unapplied. Follow the permitted lookup schedule without treating repeated absence as proof that the event is invalid.
  • Release condition: An authorised lookup or incoming event supplies the exact required parent, followed by revalidation.
  • Limits and owner: Maximum three remote attempts. Review is due thirty minutes after receipt, even if fewer attempts were possible.
  • Hypothetical outcome: At the deadline, the case moves to review_required. The integration operator must assign reconciliation, close it with evidence, or approve a new hold with a reason and another review deadline.

5. Make retrieval answer the actual dependency

A successful lookup is not necessarily a successful resolution. Check whether it returned the correct workspace's object, the required version, and enough context for this event. A current snapshot can describe what exists now without proving how an earlier delta should be applied.

Where the application deliberately supports snapshot reconciliation, treat it as a separate operation. Define which pending events the snapshot supersedes and what prevents an old event from overwriting newer state. Do not disguise reconciliation as ordinary replay.

For temporary lookup failures, use bounded backoff and a shared request budget so many held events do not overwhelm the source. Where multiple events require the same prerequisite, coordinate their lookup work while preserving each event's individual disposition.

HTTP 429 indicates rate limiting, and a Retry-After header may specify when to retry, according to MDN's HTTP 429 reference. Respect the applicable source documentation. If the permitted retry falls beyond your review deadline, escalate on time rather than retrying early or hiding the delay.

6. Release held events without replaying business effects

When context arrives, do not simply push every waiting event back through an unrestricted handler. Recheck whether each event is still applicable. The record may have advanced, the reference may have been deleted, or another recovery path may already have resolved the change.

  • Revalidate the dependency: Match the exact reference, workspace, and required version.
  • Control concurrent release: Use a durable claim or equivalent coordination so a timer and a dependency-arrival worker do not apply the same event together.
  • Protect against duplicates: Check the persisted application outcome before repeating state changes or scheduling downstream actions.
  • Record the transition: Preserve why the event became ready, which context resolved it, and whether application succeeded.

External side effects need separate care. Resolving a missing parent does not itself authorise a message, notification, or other action. If a crash occurs after an external action but before its outcome is recorded, reconcile that uncertainty before blindly repeating it. A dependency workflow should reduce ambiguity, not move it downstream.

7. Make expiry produce a decision, not another timer

A review deadline is useful only if expiry changes responsibility. Move the case out of unattended retry and present a reviewer with the missing prerequisite, evidence gathered, attempts made, latest source response, affected work, and permitted next actions.

The reviewer should be able to choose among supported recovery paths: repair local ingestion, perform authorised reconciliation, close without application, or extend the hold with a documented reason and a new deadline. An extension should identify what new evidence is expected. “Try again later” is not a sufficient recovery plan.

Watch for dependency cycles as well. If two records each wait for the other, more retries cannot establish an order. Escalate the cycle for an explicit application strategy rather than increasing the waiting period.

Avoid changing identifiers or fabricating predecessor state just to clear the queue. A visible unresolved exception is preferable to an apparently successful event that silently corrupts business history.

8. Measure whether held work reaches a useful outcome

Track held-event age, dependency reason, time to resolution, remote attempts, deadline breaches, and final disposition. Keep “closed without application” separate from “applied” so cleared backlog does not masquerade as completed business work. Check whether several events share one missing parent; event count alone can exaggerate the number of independent failures.

For your next operational review, fill this worksheet structure with actual unresolved cases. Give every case a named owner, an evidence-based release condition, an attempt budget, and a review deadline. Then review every expired case and identify which ones lack a recorded disposition.

The observable goal is not an empty queue at any cost. It is that every event either applies with valid context, remains on a justified bounded hold, or reaches a documented human decision.

Webhook processingEvent dependenciesRetry designOperational reliability

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