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
bodyTemplatefor the standard body, or send your own (Your own body). - The answer (
201 Created) has the endpoint, with itsid, and itssigningSecret, shown only this once. Keep theid: 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 sameurlreturns the same endpoint and secret with200 OKinstead 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 asAuthKey), or one sent with"secret": true. Those show"secret": true, novalue, 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 asiPaaS.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.