Skip to main content
Register a URL and Agent37 sends it a small signed JSON event every time one of your workspace’s instances changes status: created, running, sleeping, stopped, failed, deleted, and every status in between. Your code learns that a sandbox started or went to sleep without calling GET /v1/instances/{id} to ask. A webhook covers every instance in the workspace. A workspace can hold 5.

Register a webhook

string
required
Where to send events. It must be an https URL with a public hostname. http, an IP address, localhost, or a username and password in the URL return 400 invalid_request.
string
The webhook’s id, used to delete it.
string
The URL you registered.
string
The signing secret, used to verify that an event came from Agent37. It is returned in this response only, so save it. To rotate it, delete the webhook and register it again.
object | null
null while events are being delivered. After an event has failed every try it is { "at", "status", "error" }: at is epoch seconds, status is the HTTP code your URL answered with, or null with error set to timeout, connection_failed, or tls_error. The next event that is delivered sets it back to null.
integer
Unix seconds when the webhook was registered.
A sixth webhook returns 409 webhook_limit_reached.

The event

Each event is a POST to your URL with a JSON body and three headers.
string
Always instance.status.updated. Check it anyway, so your handler ignores event types added later.
string
When the status changed, as an ISO 8601 time with milliseconds. This is the time of the change, not of the send.
string
The instance.
string
The status the instance is in now. Any of the instance statuses.
string | null
The status it left. null on the first event of a new instance, whose status is provisioning.
object | null
The same status_reason the instance object carries, which says why an instance is failed.
string | null
The instance’s name.
object | null
The instance’s metadata, so you can route the event to your own user or job without calling the API.
A create sends provisioning, then running once the instance is up. A delete ends with deleted, after which the instance id returns 404.

Verify the signature

Events are signed the Standard Webhooks way, so the standardwebhooks library for your language verifies them with the secret from the create response. Pass it the raw request body, exactly as received, and the request headers. It raises an error when the signature does not match or the event is more than five minutes old.
To verify by hand, compute HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{body}, keyed with the base64-decoded bytes of the secret after its whsec_ prefix, and compare the base64 result with the value after v1, in webhook-signature.

Delivery

  • Answer with any 2xx within 5 seconds. Anything else, a redirect included, is a failed try.
  • A failed event is tried 3 times: at once, about 1 second later, then about 5 seconds after that. After the third it is dropped and the webhook’s last_failure records why. If your receiver was down, call GET /v1/instances to catch up.
  • Events can arrive out of order. A create goes through its statuses in about a second, and the sends race each other. Keep the event with the newest timestamp for each instance and ignore older ones.
  • webhook-id is the same on every try of one event, so you can drop a repeat.
An event is sent only when the status changes. A program that crashes and is restarted inside a running instance sends nothing; read its health from logs. When a request to a sleeping instance’s URL wakes it, the running event is sent after the instance has already taken that request.

List webhooks

The list never includes secret.

Delete a webhook

Deleting acts once: a repeat returns 404 not_found.