Callback Handler

Overview

Callback Handler is the server-side component that receives, validates, records, and processes callback requests. It is used to translate external asynchronous messages into safe internal state changes. It differs from the callback URL, which only identifies where the handler can be reached.

A typical implementation works as follows: The handler reads the raw request, verifies authenticity, validates the schema and identifiers, records the event durably, acknowledges, and dispatches processing. Replay of Callback Handler should preserve original identifiers and timestamps so historical processing cannot masquerade as a new event.

Common risks include slow work and non-idempotent updates. For payment systems, the implementation must preserve identifiers, environment, version, and final operational state. Important failure modes include slow work, non-idempotent updates, trusting browser input, weak signature handling, and missing transaction checks. These failures can duplicate or misapply payments.

Core controls require teams to separate receipt from processing, authenticate first, validate amounts and state, deduplicate, use transactions or queues, and preserve audit evidence. For Callback Handler, the event identifier, signature result, delivery attempt, and resulting business state should remain connected throughout processing.

Operational evidence should include handler version, event ID, signature result, object and transaction IDs, response, processing state, and exception. Callback Handler should be documented alongside Callback URL, Callback Verification, and Callback Retry. The Callback Handler path should preserve ordering and duplicate evidence so delayed delivery cannot silently overwrite a newer state.

Recovery for Callback Handler should combine replay controls with an authoritative status check rather than trusting delivery history alone. A Callback Handler handler should acknowledge only after durable receipt when the provider’s retry contract depends on the response.