Back to all articlesWebhook processing

Decide Whether to Apply, Ignore, or Hold a Late Webhook Event

Alactic Editorial10 min read

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

A customer record already shows a new account owner when an older webhook arrives naming the previous owner. Applying the payload would undo a valid update. But discarding every late event is also unsafe: a delayed event might record a separate payment, a missing activity, or a change that must be applied before another change.

To handle out-of-order webhook updates, first identify what the event means. Apply a versioned snapshot only when its documented version is newer than the state you have committed. Ignore an older snapshot only when it contains no independent work you still need to process. Hold an event when its ordering, prerequisites, or meaning are uncertain, then resolve that uncertainty through a source-state check or event-history reconciliation.

Arrival time tells you when your system received a message—not when the business change happened. The decision sheet below turns that distinction into a repeatable operating rule.

1. Define what apply, ignore, and hold actually do

These decisions should have distinct outcomes, not just different log messages.

  • Apply: commit the event’s permitted effect to the relevant local state, with a record of the evidence used to accept it.
  • Ignore: make no further change for this event because there is sufficient evidence that its relevant effect is already represented or superseded. Retain the decision record.
  • Hold: preserve the event without applying its uncertain effect. Assign a reason, a resolution action, and an owner or automated reconciliation process.

Holding is not the same as repeatedly retrying the same write. If the payload lacks reliable ordering evidence, another attempt will not create that evidence. A held event needs a different action: check current source state, obtain missing history, validate a version contract, or ask an operator to resolve a conflict.

These are processing decisions, separate from the transport response returned to the sender. A recommended design records receipt durably before acknowledging it, while following the sender’s documented delivery contract. Neither an acknowledgement nor a successful handler run proves that the underlying business state is correct.

2. Establish the event contract before comparing values

For each event type, document the ordering evidence you can actually rely on. Do not infer a contract from field names such as updated_at, version, or sequence.

  • Entity and scope: Which record does the event describe? Does its ordering value apply to that record, a child record, a field, or a larger stream?
  • Meaning: Is it a complete snapshot, a partial replacement, an incremental change, or a record of an occurrence?
  • Ordering guarantee: Does the source document how versions or sequences increase, whether they can reset, and how equality should be interpreted?
  • Timestamp meaning: Does the time describe creation, source commit, publication, or some other step? Is it documented as suitable for conflict resolution?
  • Recovery evidence: Can you fetch current state, retrieve missing changes, or otherwise establish whether an effect is already included?

A version is useful only within its documented scope. A contact version cannot safely order a payment event merely because both payloads contain the same contact ID. Likewise, a source timestamp and a locally recorded modification time are not automatically comparable.

Record unknowns explicitly. “Ordering not documented” is a legitimate contract status and a reason to avoid destructive replacement—not a reason to silently choose arrival order.

3. Use this filled late-event decision sheet

Fictional worked example: The following decision table is presented as a row-by-row list for easy copying into an operating document. All records, values, and source contracts are hypothetical. Each row specifies the event, the evidence, the decision, and the follow-up.

  1. Versioned full snapshot: older revision. Local account state is revision 42; the delayed snapshot is revision 40. The hypothetical source documents increasing per-account revisions, and the payload contains only account state.

    Decision: ignore the snapshot. Keep revision 42. Record older_snapshot with both revisions. No source check is needed unless another inconsistency is present.

  2. Versioned full snapshot: newer revision with a gap. Local state is revision 42; the arriving snapshot is revision 45. The hypothetical contract says the snapshot is complete for this projection and intermediate revisions are not required to reconstruct it.

    Decision: apply conditionally. Replace the covered state only if the stored revision is still below 45 at commit time. This updates current state; it does not prove that any separate obligations attached to skipped events have been handled.

  3. Same revision, conflicting content. Local revision 42 names one owner; another payload at revision 42 names a different owner. The hypothetical contract does not permit that difference.

    Decision: hold and check the source. Do not choose whichever arrived last. Compare the documented state fields, investigate the inconsistency, and reconcile from a supported authoritative read.

  4. Timestamped partial update with no ordering guarantee. Local owner information was changed after an incoming event’s updated_at value, but the source does not document that timestamp as a reliable ordering key.

    Decision: hold the conflicting field update. Check current source state if that source owns the field. Do not treat the older-looking timestamp as proof that the event is obsolete.

  5. Timestamped field update with a documented ordering contract. A hypothetical source guarantees a strictly ordered commit timestamp for one field. The incoming field timestamp is earlier than the stored timestamp for that same field.

    Decision: ignore that field update. Retain the newer value. This rule does not extend to unrelated fields, other sources, or equal timestamps without a documented tie rule.

  6. Incremental change with a missing predecessor. Local balance projection is complete through sequence 17. An event at sequence 19 says to subtract a hypothetical 3 units. The contract requires contiguous application.

    Decision: hold. Retrieve or reconcile sequence 18, then apply verified changes in order. A current balance alone may repair the balance projection without recovering the missing activity history.

  7. Late independent occurrence. A delayed activity has a unique occurrence ID not present in the local activity ledger. A newer profile snapshot has already been applied, but the documented activity semantics are independent of profile revision.

    Decision: apply the activity once. Add the missing occurrence without replacing current profile fields. A newer snapshot does not establish that the activity was processed.

  8. Incremental change after snapshot reconciliation. A late adjustment arrives after a source-state check replaced the local total. The read response does not identify which adjustments it includes.

    Decision: hold and check inclusion. Obtain an event ledger or a documented snapshot boundary before applying the adjustment. Otherwise, applying it may count it twice, while ignoring it may lose it.

The central distinction is whether the event replaces state or contributes something distinct. An older snapshot can be obsolete while an older occurrence remains necessary.

4. Protect the decision at the moment of writing

A correct comparison can still produce stale state if the check and write are separate. Two handlers might both read the same local revision, independently accept their events, and then write in the opposite order.

Use a conditional write or an equivalent transactional guard. For a documented increasing snapshot revision, the intended rule is:

Apply the incoming snapshot only if
its revision is greater than the stored revision
at the moment the state change commits.

If the condition fails, read the committed state again and re-evaluate. Do not force the write merely because the event passed an earlier check.

The stored revision must describe state actually committed, not simply the highest event observed. Receiving a higher revision does not mean its contents were successfully applied.

For independent incremental changes, record the event’s processing identity and its state effect atomically where possible. Otherwise, a failure between those steps can produce either a duplicated effect or an event marked complete without its effect.

This is different from ordering. Duplicate detection answers whether this event has already been handled. Version comparison answers whether its state should replace current state. A robust decision often needs both.

5. Make source-state checks answer a precise question

“Fetch the latest record” is not a complete recovery rule. Before reading from the source, specify what the read must establish.

  • For a snapshot conflict: Which values are authoritative now, and what revision or documented ordering token belongs to them?
  • For a missing incremental change: Which events are absent, and in what order must their effects be applied?
  • For a possible duplicate adjustment: Is this specific occurrence already represented in the reconciled state?
  • For competing edits: Which system owns the disputed field, and are there local changes that a replacement must preserve?

A source read also needs an interpretation rule. If it returns no usable version or inclusion boundary, it may establish current values without resolving whether a delayed adjustment is already included. If its freshness is uncertain, it may not justify an overwrite at all.

When usable version information is available, apply the read result under the same commit-time guard as any other snapshot. A webhook can advance local state while the read is in flight.

If the source is unavailable, keep the event held and retry the check under a bounded recovery policy. Escalate unresolved cases rather than converting uncertainty into an automatic overwrite. A temporary delay is often less damaging than silently replacing verified current information.

6. Separate state repair from business side effects

Restoring current state does not necessarily restore every action associated with past events. A snapshot can show that an order is complete without proving that a required internal task was created. Conversely, replaying old events can repeat actions that already occurred.

Track state projection and side-effect completion separately. A decision to ignore stale profile fields should not automatically discard an independent activity in the same payload. A decision to apply a newer snapshot should not automatically trigger every transition implied by the difference between old and new values.

Before allowing an event to initiate an external action, require a separate eligibility decision, appropriate authorisation, and a duplicate-action guard. Historical replay should not inherit live-action permission by accident.

The trade-off is additional bookkeeping. The benefit is a clearer recovery boundary: you can repair a record without silently repeating a customer-facing action, and you can recover a missing task without rolling back the record.

7. Give held events a route back to completion

A hold process needs an exit condition. Otherwise it becomes a growing collection of unresolved data problems.

For each held event, retain the event identity, entity scope, event type, relevant incoming and stored ordering evidence, hold reason, next action, and decision history. Keep payload access limited to what operators need, and follow your data-retention rules.

Useful reason codes include ordering_unknown, missing_predecessor, equal_version_conflict, and inclusion_unknown. These separate problems that require documentation from those that require a source read or engineering investigation.

Define completion evidence for each reason. A missing-predecessor hold can close when the required sequence is reconstructed or an approved reconciliation establishes a new boundary. An unknown-inclusion hold needs evidence about inclusion, not merely a successful retry.

If an incorrect stale write has already occurred, pause the affected action path where appropriate, capture the conflicting evidence, restore state through the verified reconciliation rule, and inspect any dependent actions. Repairing a field does not undo a notification or another external effect.

8. Test one event type before widening the rule

Start with one business-critical event type. Document its meaning and ordering contract, then run a controlled replay using fictional records.

  • Deliver an older snapshot after a newer one.
  • Deliver the same event twice.
  • Deliver conflicting content at an equal version.
  • Omit a required predecessor.
  • Make a source-state check fail.
  • Let local state advance while that check is in flight.
  • Replay an incremental event whose inclusion in a snapshot is unknown.

For every case, specify the expected final state, decision reason, hold exit condition, and permitted side effects before running it. Compare those expectations with both the stored record and the action log.

Your next measurable step is to complete this exercise for one event type and account for every replayed event as applied, ignored with evidence, or held with an assigned resolution action. Track unresolved holds by reason and age. That makes uncertainty visible without pretending that arrival time can settle it.

WebhooksData integrityEvent processingCRM operations

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