Subscribing to webhooks

Webhooks tell your system when something happened on an account, so you do not have to poll. Subscribing is one call per account per event.

subscribe.shbash

curl -X POST 'https://customer-api.prod.xace.io/webhooks/subscribe' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "zapId": "recon-eur-ops-received",
    "xaid": "11afa99b-9111-4111-8dab-f089295c1111",
    "url": "https://hooks.example.com/xace",
    "event": "TransactionReceived"
  }'

Field	Meaning
zapId	Your identifier for this subscription. You will need it to unsubscribe, so make it meaningful and store it.
xaid	The account to watch. One subscription covers one account.
url	Your HTTPS endpoint.
event	TransactionConfirmed or TransactionReceived.

The response is 201 with a ref, the account, the event type and the endpoint details as registered.

The two events

TransactionReceived: money arrived on the account. Use it to react to PSP settlements and customer deposits.
TransactionConfirmed: an outgoing transaction has settled. Use it to mark payouts as complete.

Subscribe to both on each account you care about. Two accounts and two events is four subscriptions.

More events through Connections

The web app's Connections page and the Zapier integration expose a wider set of events, including PaymentRequested, PaymentApproved, PaymentDeclined, PayeeCreated and card events. If you need those, see [Zapier, Slack and Xero without code](/guides/zapier-slack-and-xero-without-code) or the [API and webhooks introduction](https://support.xace.io/en/articles/16186395-read-api-introduction-and-webhooks).

Unsubscribe

unsubscribe.shbash

curl -X DELETE 'https://customer-api.prod.xace.io/webhooks/unsubscribe' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "zapId": "recon-eur-ops-received" }'

Unsubscribe before you decommission an endpoint. A subscription pointing at a dead URL generates failed deliveries and noise.

Before you rely on it

Verify every delivery's signature. See Validate Webhooks.
Treat the webhook as a signal, not the record. On receipt, fetch GET /transaction/{xtid} for the full, current transaction. See Designing a webhook consumer.
Keep polling as a fallback for the first few weeks. Compare what webhooks told you with what the transaction sync found. When they agree for a month, you can lean on the webhooks.