Webhooks
A webhook tells your server that a job reached a new state. Each delivery has a JWT signature. You verify it with the public keys of your organization. There is no shared secret.
Subscribe
Use one of two methods. They work together.
Per job. Add notify to the body of a capability call:
notify also accepts { "endpoint": "whe_…" }, the id of a saved endpoint. An unknown id gives 400 invalid_request, and the API creates no job. Endpoint ids of /v1 do not work on /v2.
Per organization. Add an endpoint on the Webhooks page of Dash. Select Add endpoint, enter the URL and select the events. With no event filter, the endpoint gets every event. An organization has at most 20 endpoints.
The notify target of a job gets every event of that job. An endpoint with a matching filter gets the event too. The API sends one delivery per URL.
The URL must use https, with 512 characters or fewer. The API refuses internal hosts and hosts on cloudraker.run. The API checks the URL again before each attempt.
Events
The body
The body is JSON. data.job is the Job object:
Verify the signature
The x-cr-signature header holds a JWT. The public keys are at the JWKS of your organization:
- Read the raw body bytes. Do not parse and serialize the JSON first.
- Verify the JWT signature with the key that has the
kidof the JWT. Allow RS256 only. - Check
iss,audandexp. - Compute the SHA-256 of the raw body and compare it with
body_sha256. - Drop a delivery with a
jtithat you already processed.
The /v1 webhook verifier does not verify a v2 webhook. /v1 uses another header, issuer and claim set.
Retries
Each attempt signs the body again with the same jti. After the fifth failed attempt, the delivery status is failed. The Webhooks page of Dash shows each delivery and can replay it. A replay uses the same jti.