Set the webhook URL, or rotate its secret
- In the sandbox
In plain words
The operator's key sets the operator's webhook, which gets every client's events; a client's admin key sets that
client's own, which gets only its events. The first call needs url and creates the secret, which is returned once. Rotating returns the new secret
once. For 24 hours the service signs each delivery with both the new and the old secret, so the partner can
switch without losing events. Only events written after the first call are delivered.
The URL must be https, and every address its host resolves to must be public: loopback, private, link-local, carrier-grade NAT, multicast, reserved and cloud metadata addresses are refused, here and again before each delivery. Redirects are not followed.
Since 0.16.0 any query parameter answers 400, so a misspelt client can never change the operator's own webhook.
apiKeyAuthorizationBearer <token>Send your key as a bearer token: Authorization: Bearer <your-api-key>. Health is the only call that needs no key.
application/json- body
url?string^https://uriactive?booleanrotate_secret?booleanfalsecontact_email?|length <= 254Saved.
application/json- response
url*|^https://uriactive*booleansecret_rotated_at?|date-timecontact_email?|Who to tell when deliveries die.
last_delivery?|nullsecret?stringPresent only when a secret was created or rotated in this call.
curl -X PUT "https://example.com/webhook" \ -H "Authorization: Bearer <your-api-key>" \ -H "Content-Type: application/json" \ -d '{}'{ "url": "http://example.com", "active": true, "secret_rotated_at": "2019-08-24T14:15:22Z", "contact_email": "string", "last_delivery": { "at": "2019-08-24T14:15:22Z", "http_status": 0 }, "secret": "string"}Get the webhook settings (the operator's, or with a client's admin key that client's own) GET
Since 0.16.0 the operator's key reads one client's settings with client. A client's admin key may name only its own client; any other answers 404. An unknown or repeated parameter, or client given empty, answers 400. Setting and testing a webhook take no query parameters at all (400): they stay with the webhook's own key.
Send a signed test event to the webhook URL POST
The body has event_id, type (always test), occurred_at and message, signed like a status event. It reports no invoice. Since 0.16.0 any query parameter answers 400.