Get the webhook settings (the operator's, or with a client's admin key that client's own)
- In the sandbox
In plain words
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.
apiKeyAuthorizationBearer <token>Send your key as a bearer token: Authorization: Bearer <your-api-key>. Health is the only call that needs no key.
client?stringThe operator's choice of client. Another shape answers 400.
^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$Current settings. The secret is never returned. With nothing set, url is null and active false.
application/json- response
url*|^https://uriactive*booleansecret_rotated_at?|date-timecontact_email?|Who to tell when deliveries die.
last_delivery?|nullcurl -X GET "https://example.com/webhook" \ -H "Authorization: Bearer <your-api-key>"{ "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 }}Build and check a document without sending it POST
Runs the schema, the pre-checks, the serializer for the route and every official validation layer, then returns the report and the documents it built, each with its bytes in content_base64 when it is 2 MiB or smaller. Nothing is sent and nothing is stored beyond the request log. Use it while mapping a new client. A number past the limits (see the conventions) answers 422 before any check runs.
Set the webhook URL, or rotate its secret PUT
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.