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

# Webhooks

> Receive payment-intent updates at your own endpoint, registered through the Zeam business portal.

Webhooks push payment-intent lifecycle updates to an endpoint you control, so
you do not have to poll. They are how you learn, asynchronously, that a payment
you executed has progressed, succeeded, failed, or was refunded.

## Where webhooks fit

A payment is asynchronous: you [execute a payment](/api-reference/introduction)
and the gateway accepts it for processing. From there, you track progress two
ways:

* **Webhooks**: Zeam calls your endpoint when the intent changes state.
* **Polling**: you read the intent state on demand with
  `GET /v1/intents/{intentId}`.

Webhooks are the recommended path for production integrations.

## Registering a webhook

<Info>
  You register and manage webhook endpoints in the **Zeam business portal**, not
  through this API. The gateway only lets you **list** your registrations with
  [`GET /v1/webhooks`](/api-reference/introduction).
</Info>

An association administrator registers webhooks in the business portal under
**Settings → Webhooks**. Registration is admin-only. For each registration you
provide:

* A destination **URL** that must use `https` and be publicly reachable
  (`localhost` is rejected).
* One or more **event types** to subscribe to (see below).

You can register multiple event types at once. There is **one webhook per
association and event type**: registering a type that already exists is
rejected, and a disabled type cannot be re-registered.

<Warning>
  Disabling a webhook is permanent. The registration is deactivated and cannot
  be reactivated, and the same event type cannot be registered again.
</Warning>

## Supported event types

The gateway emits payment-intent events. The value is what the registration
stores; the wire key is the dotted name on the delivered event.

| Event                | Wire key               | Meaning                                  |
| -------------------- | ---------------------- | ---------------------------------------- |
| `IntentInitiated`    | `intent.initiated`     | A payment intent was initiated.          |
| `IntentProcessing`   | `intent.processing`    | A payment intent is being processed.     |
| `IntentSuccessful`   | `intent.successful`    | A payment intent completed successfully. |
| `IntentFailed`       | `intent.failed`        | A payment intent failed.                 |
| `IntentRefunding`    | `intent.refunding`     | A refund is in progress.                 |
| `IntentRefunded`     | `intent.refunded`      | A payment intent was refunded.           |
| `IntentRefundFailed` | `intent.refund.failed` | A refund failed.                         |
| `IntentCancelled`    | `intent.cancelled`     | A payment intent was cancelled.          |

## Testing a registration

The business portal can send a **test event** to an active registration, so you
can confirm your endpoint receives and acknowledges deliveries before relying on
real traffic.

## What to prepare before registering

* A public `https` endpoint that is reachable from the internet.
* Fast acknowledgement: respond with a `2xx` quickly and process asynchronously.
* Idempotent handling: be ready to receive the same event more than once and
  de-duplicate on the event's identifier.

## Listing your webhooks

Use the gateway to see what is registered for your association:

```bash cURL theme={null}
curl -sS https://api.zeam.app/v1/webhooks \
  -H "Authorization: Bearer $ZEAM_TOKEN" \
  -H "x-zeam-auth: $ZEAM_APP_SECRET"
```

Each item includes `id`, `url`, `type`, `isActive`, and `createdAt`. See
[`GET /v1/webhooks`](/api-reference/introduction).

## Not yet documented

The delivery contract is owned by Zeam's notification system and is not yet
published here.

<Warning>
  Do not build signature verification or retry handling against assumptions.
  These details are pending confirmation.
</Warning>