POST request when a sandbox is running, stopped, failed, or deleted. You do not have to read the sandbox again and again.
Write the code that receives sandbox webhooks.
Before you start
- You need an API key with the
webhooks:writescope. A key withwebhooks:readcan only list and get the endpoints. See API keys. - You need an HTTPS URL that the internet can reach. The API refuses
http://URLs and private addresses, such aslocalhostor10.0.0.1.
Add an endpoint
SendPOST /v1/webhooks with the url. Send events to get only some events. The default is each event. See the list of events.
201 with the endpoint and its secret:
409.
Check the signature
Each request has these headers:
Calculate the signature from the raw body, before you parse the JSON. Use the secret of the endpoint as the key. Compare in constant time, and refuse a timestamp that is more than 5 minutes from your clock.
Answer the request
Answer with a2xx status within 10 seconds. Do long work after you answer.
If the endpoint answers with a different status, answers too late, or cannot be reached, the request comes again. Each event has up to 8 attempts. See the retry times.
An event can come more than one time. Each attempt has the same event ID. Keep the IDs that you processed, and ignore an ID that you already have. Events can come in a different sequence from the changes. Use createdAt of the event to find the latest change.
Change or delete an endpoint
- Send
PATCH /v1/webhooks/{id}with the fields to change. Send"enabled": falseto stop the events and keep the endpoint. - Send
DELETE /v1/webhooks/{id}to delete the endpoint. Attempts that wait for a retry stop. - Send
GET /v1/webhooksto list the endpoints. The list does not show the secrets. - Send
POST /v1/webhooks/update-manywithitems, orPOST /v1/webhooks/delete-manywithids, to change or delete up to 500 endpoints in one request. The answer has a result for each item. There is no create of many endpoints, because the API shows the secret of an endpoint only in the answer of its create.