> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeam.money/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks overview

> Receive payment lifecycle events at your own endpoint instead of polling.

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](/api-reference/introduction), 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**: Zeam calls your endpoint when the payment changes state.
* **Polling**: you read the record yourself with
  [`GET /v1/transactions/{transactionId}`](/api-reference/introduction).

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.

<Info>
  Events tell you *when* to act; the [Transactions](/api-reference/introduction)
  API is the source of truth for the current state. Reconcile against it before
  releasing goods or funds.
</Info>

## 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](/webhooks/events)
for the full list and payload.

## In this section

<CardGroup cols={2}>
  <Card title="Create a webhook" icon="plus" href="/webhooks/create">
    Register an endpoint in the portal or through the API.
  </Card>

  <Card title="Events" icon="list" href="/webhooks/events">
    Event types, delivery headers, and the payload.
  </Card>

  <Card title="Security" icon="shield-check" href="/webhooks/security">
    Verify signatures and build idempotent consumers.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/webhooks/troubleshooting">
    Diagnose delivery problems.
  </Card>
</CardGroup>

## Endpoint requirements

* Use **HTTPS** and be publicly reachable by Zeam. Plain http is tolerated in
  the [sandbox](/access/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](/webhooks/security) for idempotent consumer guidance.