APIs and automation

Out-of-Order Webhooks: How to Stop an Old Event from Reverting a File’s State

Receipt time does not prove which change happened first. Learn to review the webhook contract and reconcile file state using verifiable criteria.

Apification
Diagram showing file events arriving in a different order and an application reconciling the file’s state

Receipt Time Does Not Prove the Order of Changes

A webhook can notify your application about an asynchronous event, but the time your server receives it does not prove when the change happened or which of two changes came first. So if every notification simply overwrites the local record, you could end up with an outdated view.

General references help explain how webhooks are used, but they do not establish an ordering contract for your integration: Stripe presents them as a way to respond to asynchronous events (Stripe documentation: https://docs.stripe.com/webhooks?locale=es-ES); Microsoft recommends Microsoft Graph webhooks for reacting to file changes in SharePoint Embedded (Microsoft Learn: https://learn.microsoft.com/es-es/sharepoint/dev/embedded/build/respond-to-changes-webhooks); and Shopify describes their use for retrieving and storing data from an event (Shopify: https://help.shopify.com/es/manual/fulfillment/setup/notifications/webhooks). To decide how to order or reconcile events, review the technical documentation for the specific provider.

The implementation patterns in this article are general recommendations, not guarantees about a platform’s delivery, ordering, or consistency. Distinguish the time of the change, the time the event was issued, and the time it was received; use fields to compare events only if the provider documents their semantics and scope.

  • Note what each time field means and the scope within which it can be compared.
  • Use local receipt time for observability, not as proof of causality.
Receipt Time Does Not Prove the Order of Changes

Model an Out-of-Order Arrival

Suppose “budget.docx” is renamed to “final-budget.docx” and then moved to an approvals folder. If the notification about the move arrives first and the one about the rename arrives afterward, applying each message as definitive truth could restore an obsolete location or name. The later delivery does not make the event the most recent change.

Before implementation, diagram the initial state, the actual changes, the notifications issued, the order of receipt, and the expected local result. Note whether each notification describes a partial change or includes a complete state; that distinction affects how it should be processed.

  • Test the case where change A happens before B, but its notification is processed afterward.
  • Check that the local record does not move backward because of the arrival order.
Model an Out-of-Order Arrival

Check the Contract Before Comparing Events

Look in the documentation for a sequence, version, or time field that the provider explicitly defines as comparable. Confirm its meaning and scope, how missing values are handled, and whether it can reset. A name such as “updated_at” or “version” is not, by itself, enough to establish that two notifications can be ordered.

If the provider documents a monotonic sequence that applies to the file, you can use it as an acceptance criterion: store the last accepted value alongside the local state and compare each notification according to the documented rules. Protect the comparison and write with an atomic operation. Define what to do with equal, missing, or invalid values instead of treating them as recent by default.

  • Document the field, its semantics, the scope of comparison, and how non-comparable values are handled.
  • An atomic update protects the local record from concurrent writes; it does not prove that every event has been received.

Without a Reliable Ordering Criterion, Consider a Reconciliation Read

If there is no documented ordering field, one possible design pattern is to treat the webhook as a notification that the file may have changed and query the resource through the API, if the provider offers that operation. Verify that you can identify the file and that the response includes the fields you need.

An API response does not, by itself, guarantee that you are reading the latest remote state: the provider’s documentation should clarify its consistency guarantees and the effect of caches, if any. If those guarantees are not documented, treat the read as a useful source of information, not as proof that the data is current.

If the read fails or cannot identify the resource, retain the local state you already have and apply a retry policy appropriate for your system. Distinguish a temporary error from confirmation that the file no longer exists.

  • Verify the read operation, required identifier, returned fields, and documented consistency guarantees.
  • Do not turn a failed read into a deletion or a confirmed update.

Protect Local Writes from Concurrent Responses

Two notifications can trigger reads at the same time. If the first takes longer and its response is saved after the second one, it could replace a result that has already been written. The order in which queries finish does not prove which response reflects more recent remote data.

You can serialize reconciliations per file or assign each request a local generation and check it when saving. That generation helps prevent an earlier local job from overwriting a later one, but it does not establish which response contains more recent remote data. The API’s documented guarantees are still needed for that. Another option is to group notifications and query after a burst, if the resulting latency is acceptable.

  • Test API responses that finish in the reverse order from which the requests started.
  • Separate protection against stale local writes from guarantees about how current the remote data is.

Test Repeats, Permutations, and Failures

Run the same set of changes with notifications in normal order, reverse order, and other permutations. Include repeated notifications: deduplication is a related problem, but it is distinct from ordering. Check the expected final state, not just the receiver’s response code.

Vary the cases: rename and move, change the location and state, rename twice, and combine partial notification fields. Add API read failures and two concurrent processes. If you work with versioned files, you can compare the local record with the available history; do not assume that history replaces an ordering contract.

  • Acceptance criterion: the tested permutations do not make the record move backward relative to the state verified under the available guarantees.
  • Log delivery, read, and local update failures separately.

Log What You Need to Diagnose Discrepancies

Log a secure reference to the file, the event type, documented ordering fields if available, receipt time, the API read result, and the local write decision. Your own correlation ID can help trace a notification through to reconciliation. Avoid storing tokens, secrets, or the full file contents, and limit personal data to what is necessary.

Keep the log useful for determining whether the event was received, whether the resource could be queried, and why a write was accepted or rejected. Apification offers integration through REST API and webhooks, and its automation features include retries, history, and statistics. Consult the applicable documentation to confirm what information is available in your workflow; these features help you observe an integration but do not establish an ordering criterion.

  • Separating receipt, read, comparison, and write makes it easier to find where a divergence occurred.
  • Do not include credentials or secrets in logs.

Frequently asked questions

Can I order events by the time my server receives them?

Not as proof of which change happened first. Receipt can be delayed; use an ordering field only if the provider documents its meaning and scope.

Does an API read always return the latest state?

Not necessarily. Check the documentation for consistency guarantees and the possible effect of caches. Without that information, do not treat a response as proof that the data is current.

What should I do if the webhook does not include a sequence field?

If the API offers a suitable read and documents how to identify the resource, you can treat the webhook as a notification to start reconciliation. Also check the guarantees for the read; if there is no suitable option, consult the provider’s contract.

Does Apification guarantee that file webhooks arrive in order?

Available product information confirms integration through REST API and webhooks, as well as retries, history, and statistics for automations; it does not specify an ordering guarantee for file events. Check the applicable documentation before relying on one.

Sources and further reading

Documentation consulted while preparing this article.

Explore Apification

Related articles

Back to the blog