> ## Documentation Index
> Fetch the complete documentation index at: https://www.agent37.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Get a signed POST at your own URL every time one of your instances changes status, so you never poll for it.

Register a URL and Agent37 sends it a small signed JSON event every time one of your workspace's instances changes [status](https://www.agent37.com/docs/agents-api/instances/object.md#statuses): 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.

| Method | Path | Returns |
| - | - | - |
| `POST` | `/v1/webhooks` | `201` with the webhook object and its `secret` |
| `GET` | `/v1/webhooks` | `200` `{ "data": [...] }`, newest first |
| `DELETE` | `/v1/webhooks/{id}` | `200` `{ "id": "...", "deleted": true }` |

## Register a webhook

**url** `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`.

```bash curl wrap theme={null}
curl -X POST \
  https://api.agent37.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/agent37"
  }'
```

```python Python wrap theme={null}
import requests

response = requests.post(
    "https://api.agent37.com/v1/webhooks",
    headers={
        "Authorization": "Bearer sk_live_...",
        "Content-Type": "application/json"
    },
    json={
        "url": "https://example.com/agent37"
    },
)
response.raise_for_status()
print(response.json())
```

```javascript Node wrap theme={null}
const response = await fetch(
  "https://api.agent37.com/v1/webhooks",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_live_...",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "url": "https://example.com/agent37"
    }),
  },
);
if (!response.ok) {
  throw new Error(await response.text());
}
console.log(await response.json());
```

```json response wrap theme={null}
{
  "id": "k3m9x2p7qa",
  "url": "https://example.com/agent37",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw6Yv1mF4bYzk=",
  "last_failure": null,
  "created": 1794937200
}
```

**id** `string`

The webhook's id, used to delete it.

**url** `string`

The URL you registered.

**secret** `string`

The signing secret, used to [verify](#verify-the-signature) 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.

**last\_failure** `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`.

**created** `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.

```http theme={null}
POST /agent37 HTTP/1.1
content-type: application/json
webhook-id: 6f1c0d0e-2a4b-4c1e-9d3a-8b7e5f0a1c2d
webhook-timestamp: 1794940800
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
```

```json theme={null}
{
  "type": "instance.status.updated",
  "timestamp": "2026-11-17T18:40:00.123Z",
  "data": {
    "id": "ab12cd34ef",
    "status": "running",
    "previous_status": "starting",
    "status_reason": null,
    "name": "ci-runner-7",
    "metadata": { "user": "u_42" }
  }
}
```

**type** `string`

Always `instance.status.updated`. Check it anyway, so your handler ignores event types added later.

**timestamp** `string`

When the status changed, as an ISO 8601 time with milliseconds. This is the time of the change, not of the send.

**data.id** `string`

The instance.

**data.status** `string`

The status the instance is in now. Any of the [instance statuses](https://www.agent37.com/docs/agents-api/instances/object.md#statuses).

**data.previous\_status** `string | null`

The status it left. `null` on the first event of a new instance, whose `status` is `provisioning`.

**data.status\_reason** `object | null`

The same `status_reason` the [instance object](https://www.agent37.com/docs/agents-api/instances/object.md) carries, which says why an instance is `failed`.

**data.name** `string | null`

The instance's `name`.

**data.metadata** `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](https://www.standardwebhooks.com) 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.

```javascript Node wrap theme={null}
import { Webhook } from "standardwebhooks"; // npm install standardwebhooks

const webhook = new Webhook(process.env.AGENT37_WEBHOOK_SECRET);

export default {
  async fetch(request) {
    const body = await request.text();
    let event;
    try {
      event = webhook.verify(body, Object.fromEntries(request.headers));
    } catch {
      return new Response("bad signature", { status: 400 });
    }
    if (event.type === "instance.status.updated") {
      console.log(event.data.id, event.data.status);
    }
    return new Response("ok");
  },
};
```

```python Python wrap theme={null}
import os
from flask import Flask, request
from standardwebhooks import Webhook  # pip install standardwebhooks

app = Flask(__name__)
webhook = Webhook(os.environ["AGENT37_WEBHOOK_SECRET"])

@app.post("/agent37")
def agent37():
    try:
        event = webhook.verify(request.get_data(), dict(request.headers))
    except Exception:
        return "bad signature", 400
    if event["type"] == "instance.status.updated":
        print(event["data"]["id"], event["data"]["status"])
    return "ok"
```

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`](https://www.agent37.com/docs/agents-api/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](https://www.agent37.com/docs/agents-api/logs.md). 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

```bash curl wrap theme={null}
curl https://api.agent37.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_..."
```

```python Python wrap theme={null}
import requests

response = requests.get(
    "https://api.agent37.com/v1/webhooks",
    headers={
        "Authorization": "Bearer sk_live_..."
    },
)
response.raise_for_status()
print(response.json())
```

```javascript Node wrap theme={null}
const response = await fetch(
  "https://api.agent37.com/v1/webhooks",
  {
    headers: {
      "Authorization": "Bearer sk_live_..."
    },
  },
);
if (!response.ok) {
  throw new Error(await response.text());
}
console.log(await response.json());
```

```json response wrap theme={null}
{
  "data": [
    {
      "id": "k3m9x2p7qa",
      "url": "https://example.com/agent37",
      "last_failure": { "at": 1794940806, "status": 500, "error": null },
      "created": 1794937200
    }
  ]
}
```

The list never includes `secret`.

## Delete a webhook

```bash curl wrap theme={null}
curl -X DELETE \
  https://api.agent37.com/v1/webhooks/k3m9x2p7qa \
  -H "Authorization: Bearer sk_live_..."
```

```python Python wrap theme={null}
import requests

response = requests.delete(
    "https://api.agent37.com/v1/webhooks/k3m9x2p7qa",
    headers={
        "Authorization": "Bearer sk_live_..."
    },
)
response.raise_for_status()
print(response.json())
```

```javascript Node wrap theme={null}
const response = await fetch(
  "https://api.agent37.com/v1/webhooks/k3m9x2p7qa",
  {
    method: "DELETE",
    headers: {
      "Authorization": "Bearer sk_live_..."
    },
  },
);
if (!response.ok) {
  throw new Error(await response.text());
}
console.log(await response.json());
```

```json response wrap theme={null}
{
  "id": "k3m9x2p7qa",
  "deleted": true
}
```

Deleting acts once: a repeat returns `404 not_found`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.