Skip to main content
An integration can set up its own webhooks, so the merchant doesn’t have to copy addresses and keys between systems. The merchant only creates an API key for you. Needs: an API key with webhooks.manage (“Set up webhooks” in the portal), plus read permissions for the records you’ll fetch, such as payments.view. Only a merchant’s Owners and Admins can give a key webhooks.manage.

Register your endpoint

GET /webhooks/scopes lists every scope, what makes it fire and where to read its record. Then register:
  • Leave out bodyTemplate for the standard body, or send your own (Your own body).
  • The answer (201 Created) has the endpoint, with its id, and its signingSecret, shown only this once. Keep the id: it’s how you change the endpoint later. Names don’t have to be unique, so don’t look endpoints up by name.
  • With an Idempotency-Key, a retry from the same API key for the same url returns the same endpoint and secret with 200 OK instead of making a second one (Safe retries).
  • Header values come back on GET, except credentials: a header named like a key, token, secret, password, signature or cookie (such as AuthKey), or one sent with "secret": true. Those show "secret": true, no value, and the last four characters of a long value (valueLast4).
  • A merchant can have up to 10 endpoints.

More than one environment

Each API key sees, changes and removes only the endpoints it registered. So two environments of your integration, such as a production server and a staging server, each with its own API key from the merchant, register the same way side by side: each gets its own endpoint, neither can touch the other’s, and both are told about the same changes. The merchant sees both in Settings → Webhooks and can turn either off on its own. Give each a name that says which it is, such as iPaaS.com and iPaaS.com (staging).

Change it

PATCH /webhooks/{id} changes only what you send:
PUT /webhooks/{id} replaces everything at once instead: a header sent without a value keeps its stored value, and headers left out are removed.

Everything else

What the merchant sees

The merchant’s Settings → Webhooks shows your endpoint as set up by your API key, and they can change, pause or delete it. If they revoke the key, you can no longer change the endpoint, but it keeps sending until they turn it off or delete it.