Do Not Let a Webhook Decide Whether You Got Paid

Summary

A payment webhook is useful because it tells another system that something happened. It may arrive quickly and trigger the next operational step without waiting for a person.

But a webhook can be late, duplicated, missed, or received in a different order from another record. If the business treats that signal as cash truth, one technical failure can create false collection alerts, stranded settlements, or duplicate effects.

A dependable payment workflow needs explicit states, confidence thresholds, replay, duplicate protection, a human exception queue, and a named source of authority. Automation should make cash status clearer and recovery faster. It should not make an uncertain payment look settled merely because one system sent a message.

The Signal Arrived. The Records Still Disagreed.

Picture a payment that appears cleared in the accounting record while another system continues to treat the balance as collectible.

Both systems have data. Only one can be authoritative for the collection decision.

In one historic reconciliation, 166 collection alerts were found to be false because they conflicted with cleared balances in the accounting system. The practical response was to make that accounting record authoritative.

That does not mean the accounting system can never contain an error. It means the workflow has a declared answer when two automated signals disagree.

Without that hierarchy, automation can repeat the disagreement faster. One system says paid. Another sends a collection warning. A third changes the job status. Staff then spend time deciding which screen to believe.

Automation needs a source of truth before it needs another trigger.

Match Payments With Honest Confidence

Incoming payments may need to be matched to jobs. Some matches are obvious, while others contain missing, duplicated, or ambiguous information.

A confidence-based approach makes that uncertainty visible.

High-confidence matches can be confirmed when the evidence meets written conditions. Ambiguous cases should enter a human review queue rather than being forced into a job record.

The important design choice is not the exact threshold. It is the existence of separate paths:

1) Clear match - proceed under defined rules.

2) Ambiguous match - hold for review.

3) No match - preserve the payment signal without inventing a destination.

A model or matching routine can help rank possibilities, but it should not make incomplete evidence disappear.

The honest status is often, "Payment received, job not yet confirmed."

That may be less satisfying than a fully reconciled dashboard, but it protects the accounting trail.

Make Every Event Safe to Replay

Webhooks fail. Networks pause. Services restart. A receiving system may process the event while failing to record that it succeeded.

The recovery plan should not depend on the original notification arriving again.

A cursor-based replay can review a recent bank-data window and recover events that the webhook missed. The process is idempotent, which means the same event can be processed again without creating a second operational effect.

Idempotency is one of those technical words that describes a plain business requirement: checking twice should not mean getting paid twice, crediting twice, or changing the same job twice.

A good replay path answers three questions:

1) What time window will be checked?

2) How does the system recognize an event it has already handled?

3) What happens when the replay finds conflicting information?

The third question still needs an exception path. Replay recovers missing signals, but it does not automatically resolve ambiguous matches.

Let Polling and Webhooks Cooperate

One payment type requires frequent polling in addition to the webhook.

The polling path and webhook effectively race. Whichever signal arrives first performs the intended action. When the second signal arrives, the duplicate guard makes it harmless.

This is more dependable than assuming one delivery method will always win. However, it works only when both paths share the same duplicate protection and state model.

Otherwise, adding a polling fallback can create the very duplication it was meant to prevent.

The operating principle is straightforward:

Multiple signals can improve reliability, but only one business effect should survive.

That requires a durable event identity or equivalent duplicate check, a clear state transition, and a record of which path acted first. The team should be able to explain why an item moved, even when two systems reported it.

Sweep the Pending Queue Against Live Data

A daily sweep can re-derive pending settlements against current data rather than trusting yesterday's state indefinitely.

One historic event involved 22 payments and roughly $90,000 of potential stranding risk. That figure is an internal learning event, not a general performance claim. It shows why a second reconciliation path matters when the normal signal leaves payments in an unresolved state.

The sweep should not merely resend every action. It should compare the pending record with live information and determine whether the state still makes sense.

Possible outcomes include:

- the settlement is now confirmed,

- the item remains legitimately pending,

- the records conflict and require review,

- or the original event was already handled through another path.

A pending state should mean the system is waiting for evidence. It should not become a quiet storage area where uncertain payments disappear.

Represent Promised Payments as Real States

A promised payment is not the same as a cleared payment. It is also more meaningful than a loose note hidden in a customer record.

Representing the promise as an explicit state allows the business to define a clearing window and the action that follows if the expected payment does not arrive.

That creates a clearer sequence:

1) Promise recorded.

2) Clearing window open.

3) Payment signal received or window expired.

4) Reconciliation completed or exception queued.

A duplicate guard also matters here. An accidental second entry should not create two promises, two reminders, or two downstream actions.

Explicit states make the workflow more honest. Everyone can see what the business knows, what it expects, and what remains unresolved.

The system should never collapse "promised," "initiated," and "cleared" into the same label simply because that makes the queue easier to close.

Keep Authority and Exceptions Human

Payment automation can confirm clear matches, recover missed events, reconcile pending records, and suppress duplicate effects. It should not autonomously decide every disagreement or collect money without the surrounding business controls.

The accounting system remains authoritative when collection alerts conflict with cleared balances. Ambiguous job matches reach a human. Exceptional states stay visible until somebody resolves them.

That boundary is not a weakness in the automation. It is what keeps the automation connected to the business record.

If you are mapping your own payment workflow, begin with four questions:

1) Which system is authoritative for cleared cash?

2) How are missed events replayed?

3) What prevents duplicate effects?

4) Where do uncertain matches wait for a person?

The related use case can help turn those answers into a controlled reconciliation workflow. Webhooks are valuable signals, but cash truth requires more than a signal.