GET /v1/instances/{id} to ask.
A webhook covers every instance in the workspace. A workspace can hold 5.
Register a webhook
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.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.
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.409 webhook_limit_reached.
The event
Each event is aPOST to your URL with a JSON body and three headers.
Always
instance.status.updated. Check it anyway, so your handler ignores event types added later.When the status changed, as an ISO 8601 time with milliseconds. This is the time of the change, not of the send.
The status the instance is in now. Any of the instance statuses.
The status it left.
null on the first event of a new instance, whose status is provisioning.The same
status_reason the instance object carries, which says why an instance is failed.The instance’s
metadata, so you can route the event to your own user or job without calling the API.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 thestandardwebhooks 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.
{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
2xxwithin 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_failurerecords why. If your receiver was down, callGET /v1/instancesto 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
timestampfor each instance and ignore older ones. webhook-idis the same on every try of one event, so you can drop a repeat.
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
secret.
Delete a webhook
404 not_found.