Skip to main content
Add a webhook endpoint to your workspace. Your endpoint then gets a signed 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:write scope. A key with webhooks:read can 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 as localhost or 10.0.0.1.

Add an endpoint

Send POST /v1/webhooks with the url. Send events to get only some events. The default is each event. See the list of events.
The API answers 201 with the endpoint and its secret:
You see the secret only in this response. Keep it in a secret store. If you lose it, delete the endpoint and add a new one.
A workspace can have 10 endpoints. An 11th endpoint answers 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 a 2xx 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": false to 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/webhooks to list the endpoints. The list does not show the secrets.
  • Send POST /v1/webhooks/update-many with items, or POST /v1/webhooks/delete-many with ids, 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.