Back to all articlesWebhook processing

Choose Whether to Process Webhook Payloads or Read Current Source State

Alactic Editorial10 min read

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

A webhook arrives saying a record changed. Your worker treats its payload as the complete current record and overwrites the local copy. That decision is safe only if the source actually defines the payload that way—and even a complete snapshot may describe an earlier moment rather than the state that exists when the worker runs.

For webhook payload versus fetching current state, use this rule: apply event data when the documented event meaning and your business task require it; reconcile from a current-state read when the task is to match the source now and a suitable read is available; use a hybrid when you need both transition history and a current projection. Fetching is not automatically safer: it can erase intermediate changes from your processing history.

The decision starts with two questions: What does this event actually contain, and what information must survive processing?

1. Separate current truth from evidence of a change

A current-state projection answers, “What should this record look like now?” An event history answers, “What changes did we receive evidence of?” Those are different outputs, even when they concern the same record.

Hypothetical example: a case changes from open to escalated and then to resolved before a worker handles either notification. Fetching the case twice may return resolved both times. That can correctly update a current-work dashboard, but it cannot establish when escalation occurred, who caused it, or how long the case remained escalated.

If the business task is displaying the latest case status, intermediate status changes may not matter. If the task is reviewing escalation handling, they do. A successful read does not mean both tasks have been satisfied.

Write the required output before choosing a processing method:

  • Current projection: converge toward the latest source state that can be observed.
  • Transition history: preserve relevant changes with their documented event meaning.
  • Action decision: decide whether an observed change warrants an authorised action, potentially after checking present conditions.

One event can support several outputs, but each needs its own completion criteria. Updating a dashboard should not silently mark transition-dependent work complete.

2. Establish the payload contract before writing update logic

Classify each event type using source documentation, not field names or a single sample. A payload that looks like a record may contain only selected fields. A field called status may describe the event outcome rather than the object's status.

  • Snapshot: a representation of a record at a documented point in time. Determine whether it is complete, partial, or limited by permissions.
  • Delta: a description of changes. Determine whether it contains replacement values, old and new values, operations, or some combination.
  • Change notification: notice that something changed, usually with identifying information. It may not contain enough data to reconstruct the change.

For each type, document what missing fields mean, whether null clears a value, how deletion is represented, and whether an event version identifies the record revision or merely the event format. Also establish whether ordering, duplicate identifiers, or revision comparisons have documented semantics.

Do not interpret a missing property as an instruction to erase it unless that behavior is part of the contract. Likewise, do not sort events by a timestamp and assume that produces authoritative record order unless the source supports that interpretation.

If the meaning remains unresolved, retain the event for investigation and mark processing as uncertain. Guessing at replacement semantics can turn an incomplete notification into destructive local updates.

3. Use this filled hypothetical decision matrix

Fictional worked artifact: the following matrix describes a hypothetical case-management integration. Its event fields, revisions, and read capabilities are assumptions for the example, not capabilities attributed to any product. Each entry uses the same decision columns so a team can copy it into an integration specification.

Snapshot event: case status representation

  • Documented meaning assumed: the payload contains the complete supported case representation at revision 18. Missing supported fields mean absent at that revision.
  • Required output: a current case list and a history of status transitions.
  • Decision: hybrid. Preserve the snapshot as event evidence; update the projection only when documented revision comparisons show it is newer. Reconcile through a read when needed and available.
  • Payload-only failure: an older snapshot delivered later can roll back the projection if applied unconditionally.
  • Fetch-only information loss: revision 18 says escalated, but a later read returns resolved. The escalation observation and its event context disappear if the payload is discarded.
  • Recovery: retain the event, prevent older revisions from replacing newer ones, and investigate unresolved gaps. Do not claim unseen transitions were recovered by reading the latest record.

Delta event: assignment changed

  • Documented meaning assumed: the payload replaces the assignee from Morgan to Priya at revision 27; omitted properties are unchanged.
  • Required output: an assignment history and an accurate current owner.
  • Decision: apply the delta to a compatible baseline and preserve the transition. Use a current-state read to repair the projection if a baseline or required predecessor is missing and a read is available.
  • Payload-only failure: applying a delta to an incompatible baseline may produce a record that never existed. Treating it as a full record may erase unrelated fields.
  • Fetch-only information loss: the case may already belong to Lee. A read reveals Lee, but not the Morgan-to-Priya handoff.
  • Recovery: mark the projection incomplete until repaired. Keep the received handoff as evidence without inventing missing handoffs.

Change-notification event: case updated

  • Documented meaning assumed: the payload identifies the case and event but contains no changed fields or historical revision.
  • Required output: a current case list only.
  • Decision: current-state reconciliation, assuming an authorised read exists. Multiple pending notices may be coalesced for this projection if no separate requirement needs each notice.
  • Payload-only failure: there is no record content to apply.
  • Fetch-only information loss: intermediate status, assignment, or priority changes cannot be reconstructed from the notice and current record.
  • Recovery: retry failed reads and leave the projection visibly pending. If no read exists, classify the requested projection as unsupported by the available data.

The important result is not choosing one model for the entire integration. It is choosing a model for each event type and required output.

4. Apply payloads only with explicit update rules

Payload application is appropriate when the event contains the information your task needs and its semantics are understood. It avoids making the event's meaning depend entirely on a later read, which may show a different state.

Define separate handlers for replacement snapshots and deltas. For snapshots, specify which local fields the source owns; a source representation should not automatically replace locally maintained notes or workflow metadata. For deltas, distinguish setting a value from incrementing, appending, clearing, or removing it.

Duplicate handling must follow those operations. Reapplying an assignment replacement may leave the same value, while reapplying an increment can change the result again. Record processing outcomes using a documented event identifier or another deliberately designed deduplication key; do not assume the object identifier uniquely identifies a change.

Where comparable revisions exist, use them to protect the current projection from regression. Where they do not, acknowledge the limitation. Receipt order alone does not establish the source's change order, and preserving all received payloads does not establish that every source change was received.

5. Treat current-state reads as observations, not time travel

Reconciliation is a good fit when the business needs the latest obtainable representation rather than every transition. But first verify that the source offers an appropriate read operation, that credentials can access the object, and that the returned fields meet the projection's needs.

A read initiated after an event is not necessarily a read of the event's revision. Nor should the design assume strongly consistent reads. If the source documents comparable versions, compare them. Without that support, describe the result as the state observed during reconciliation—not proof that it includes the triggering change.

Handle absence carefully. A failed or empty read might reflect deletion, access loss, temporary unavailability, or a query mistake. Only use it to delete the local projection when the documented response meaning supports that conclusion.

Fetching also adds a failure dependency. HTTP 429 indicates rate limiting, and a response may include a Retry-After header indicating when to retry; providers apply limits differently. Respect the source's documented behavior rather than retrying every pending notification immediately. See MDN's explanation of HTTP 429.

Coalescing pending reads can reduce redundant reconciliation work, but use it only for outputs that do not need each intermediate change. Keep transition evidence separate before combining notifications.

6. Build a hybrid with separate completion states

A hybrid should not mean “try the payload, then fetch if confused.” Give event preservation, projection updates, and downstream actions distinct responsibilities.

  1. Retain permitted event evidence. Store the payload or required fields according to your retention and access rules, with the event identity, object identity, receipt time, and interpretation version.
  2. Interpret the event. Classify it as snapshot, delta, or notification and record whether its meaning is sufficiently documented.
  3. Update the appropriate output. Apply supported changes, schedule reconciliation, or mark a missing prerequisite.
  4. Track completion separately. An event can be preserved while the projection remains pending or a business action awaits review.
  5. Evaluate actions independently. An old transition may be valid evidence but no longer justify an action under current conditions. Recheck relevant conditions and authorisation before acting.

Hypothetical example: an escalation snapshot is preserved for review, while a current read shows that the case is resolved. The history can retain the escalation without reopening the current case or issuing an unnecessary escalation task. Conversely, if the task explicitly requires reviewing every escalation, the later resolved state should not erase that obligation.

7. Recover without pretending lost history is available

Recovery should state what was repaired and what remains unknown. Rebuilding a current projection from a read can fix today's display while leaving historical gaps untouched.

  • Out-of-order snapshot: retain the evidence, but prevent a documented older revision from replacing a newer projection.
  • Delta without a usable baseline: pause application to that projection; fetch a replacement baseline if supported, or route the record for investigation.
  • Notification without a read capability: record that a change was reported, but do not fabricate the resulting record.
  • Read repeatedly behind the event: keep reconciliation pending within a bounded retry policy, then surface the unresolved state.
  • Read permission failure: investigate access rather than treating the object as deleted.
  • Missing historical interval: use historical versions or replay only if the source actually provides them. Otherwise label the gap as unrecoverable from available data.

Make these states visible to operators. A generic processed flag hides the difference between evidence stored, projection repaired, and transition history complete.

8. Validate one event type before expanding the design

Choose one consequential event type and complete the matrix with your actual documented contract. Then test duplicate delivery, reversed arrival order, a missing delta baseline, repeated read failure, and several changes occurring before the first read.

For each test, check three outputs independently: the final projection, the preserved transition evidence, and any proposed action. A projection can be correct while history is incomplete or an action is wrong.

As a measurable next step, record how many test cases produce the expected output, how many remain explicitly unresolved, and whether any silently lose required information. Also measure pending reconciliation age and cases where older events overwrite newer projections.

Approve the model only when each required output has a documented data source and a visible failure state. If the available events and reads cannot preserve the information the business needs, the right outcome is an explicit capability gap—not a processor that reports success after discarding it.

Webhook processingData synchronizationEvent semanticsIntegration 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