Callback retries need classified outcomes

What the public implementation shows

GovPayments isolates callback dispatch in a dispatcher and background worker, with configurable attempts and claim behavior and tests covering delivery outcomes.

The callback outbox sits after the financial event, allowing partner notification to fail and recover without rewriting the accepted payment or reversal. This is the implementation fact behind the note; the architectural reading begins from that visible boundary rather than from an assumed production story.

Operating principleA retry count is not a strategy until the system knows which outcomes deserve another attempt.

The decision behind the mechanism

Delivery state is persisted independently so transient network and server failures can be retried while successful or terminal outcomes leave the queue.

Blind retries can hammer a partner on permanent rejection, while treating every failed attempt as final can strand a valid notification during a short outage. The mechanism matters because it gives that failure a named boundary, durable evidence, and a controlled response instead of leaving the outcome to timing or operator guesswork.

• Persist callback payload and signing context before dispatch.
• Claim work so concurrent workers cannot double-send it.
• Classify transient and terminal responses explicitly.
• Expose attempt history and terminal items for operations.

How the control should be operated

Define status-code and exception classes, exponential delay with jitter, maximum attempts, claim expiry, and an operator path for terminal callbacks.

Partner delivery becomes resilient without allowing notification timing to redefine the government payment outcome. The reusable lesson is not to copy a class or endpoint in isolation, but to preserve the relationship between identity, state, authority, evidence, and operational ownership.