Skip to main content
Webhooks push payment lifecycle events to an endpoint you control, so you learn as soon as a payment progresses, succeeds, fails, or is refunded, without polling.

​
Why webhooks

Many flows are asynchronous. When you submit a payment (P2P, swap, or off-ramp), the gateway responds 202 Accepted to confirm the request was queued, not that it settled. The outcome is decided later. You can find out in two ways: Webhooks are the recommended path for production. Compared with polling, they give you faster updates, less API traffic, more reliable automation for long-running operations, and cleaner reconciliation. Polling remains a useful fallback for reconciliation and recovery.
Events tell you when to act; the Transactions API is the source of truth for the current state. Reconcile against it before releasing goods or funds.

​
What Zeam notifies you about

Zeam sends an event when a payment is initiated, starts processing, completes successfully, fails, or moves through a refund. See Events for the full list and payload.

​
In this section

Create a webhook

Register an endpoint in the portal or through the API.

Events

Event types, delivery headers, and the payload.

Security

Verify signatures and build idempotent consumers.

Troubleshooting

Diagnose delivery problems.

​
Endpoint requirements

  • Use HTTPS and be publicly reachable by Zeam. Plain http is tolerated in the sandbox only.
  • Respond quickly with a 2xx status, then process on a background queue.
  • Handle retries safely: an event may be delivered more than once, and events may not arrive in business-process order.
  • Reconcile using the event and transaction identifiers rather than assuming order. See Security for idempotent consumer guidance.