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 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

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.

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.

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

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:

cURL

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.

Not yet documented

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

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