# Webhooks

Get a signed HTTPS request when something happens in HQ, verify it, and recover from failures.



A webhook endpoint is a URL of yours that HQ calls when an event happens in your organization: a
reply to your prompt finished, an operation settled, a secret changed. Every request is signed, so
your receiver can prove it came from HQ.

## 1. Add an endpoint [#1-add-an-endpoint]

In HQ, open **Settings, Developers, Webhooks** and choose **Add endpoint**, or call the API with a
key that holds `webhooks:manage`:

```bash
curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $HQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/hq", "enabled_events": ["session.*", "operation.failed"] }'
```

```json
{
  "object": "webhook_endpoint",
  "id": "we_…",
  "url": "https://hooks.example.com/hq",
  "enabled_events": ["operation.failed", "session.*"],
  "status": "enabled",
  "secret_prefixes": ["whsec_MfKQ"],
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw…"
}
```

* **The `secret` is shown once.** Store it in your secret manager. HQ cannot show it again; if you
  lose it, roll it. A retry with the same `Idempotency-Key` answers the same endpoint without
  `secret`, with `secret_omitted: true`.
* The URL must use `https`, port 443 or 8443, and a host name that resolves only to public
  addresses (otherwise, or when the name does not resolve, `422 host_not_allowed`). HQ checks it
  again before every delivery.
* Subscribe to exact types (`session.turn.completed`) or a whole namespace (`session.*`).
* `team_ids` limits the endpoint to some AI teams. Organization events (API keys, webhooks) still
  arrive. A key restricted to some AI teams cannot manage endpoints (`403 team_restricted`);
  reading, it sees only its own teams in `team_ids` and only the deliveries and events about its
  teams.
* `include_message_text: true` sends the message text in event bodies. Turning it on needs a key
  with `sessions:chat.read`, made by someone who holds it for every AI team (an owner or admin).
* Every owner and admin of your organization is emailed when an endpoint is added or its URL
  changes.
* An organization on a trial cannot add endpoints. Each plan allows a number of endpoints.

## 2. Verify every delivery [#2-verify-every-delivery]

Each delivery is a `POST` of one event with three headers, following
[Standard Webhooks](https://www.standardwebhooks.com/):

| Header              | Value                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------- |
| `webhook-id`        | The event id (`evt_…`). It stays the same across retries and replays.                 |
| `webhook-timestamp` | When this attempt was sent, in Unix seconds.                                          |
| `webhook-signature` | `v1,<signature>`, or two of them separated by a space while a secret is being rolled. |

The signature is a base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{raw body}`, keyed by
the base64 part of your `whsec_` secret. Use a Standard Webhooks library rather than writing the
check yourself:

```ts
import { Webhook } from 'standardwebhooks';

const wh = new Webhook(process.env.HQ_WEBHOOK_SECRET!);

app.post('/hq', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    // Throws on a bad signature or a timestamp more than 5 minutes away.
    event = wh.verify(req.body.toString('utf8'), req.headers);
  } catch {
    return res.status(400).end();
  }
  res.status(204).end(); // answer quickly, then do the work
  handle(event);
});
```

```python
from standardwebhooks.webhooks import Webhook

wh = Webhook(os.environ["HQ_WEBHOOK_SECRET"])
event = wh.verify(request.get_data(as_text=True), request.headers)
```

* Verify the **raw** body, before any JSON parsing or reformatting.
* Refuse a timestamp more than 5 minutes from your clock.
* Every request also carries `HQ-Event-Type`, `HQ-Delivery-Id` and
  `User-Agent: AIWorkforceOne-Webhooks/1`.

## 3. The event [#3-the-event]

The body is the same envelope `GET /v1/events/{event_id}` returns:

```json
{
  "id": "evt_…",
  "object": "event",
  "type": "session.turn.completed",
  "api_version": "2026-11-01",
  "created_at": "2026-11-03T08:01:12.000Z",
  "org_id": "org_…",
  "team_id": "team_…",
  "resource": { "type": "session", "id": "sess_…" },
  "data": { "session_id": "sess_…", "message_id": "msg_…", "last_item_id": "item_…" }
}
```

Payloads are thin: ids, names and statuses, never a secret value or transcript text. Read the
details you need with the API.

| Type                                                 | When                                                                            |
| ---------------------------------------------------- | ------------------------------------------------------------------------------- |
| `session.turn.completed`                             | The reply to a prompt you sent with `POST /v1/sessions/{id}/messages` finished. |
| `session.message.status_changed`                     | That prompt moved (`typing`, `delivered`, `unconfirmed`, `failed`, …).          |
| `operation.completed`, `operation.failed`            | A Cloud Computer operation or a webhook replay settled.                         |
| `secret.created`, `secret.updated`, `secret.deleted` | A secret changed. The name and scope only.                                      |
| `api_key.created`, `api_key.revoked`                 | An API key was created or revoked.                                              |
| `webhook_endpoint.disabled`                          | One of your endpoints was switched off.                                         |
| `webhook.test`                                       | You pressed Test, or called `POST /v1/webhook_endpoints/{id}/test`.             |

**Delivery is at least once, and order is not guaranteed.** Deduplicate on `webhook-id`, and use
`created_at` to ignore an update older than one you already have.

## 4. Retries and failures [#4-retries-and-failures]

Answer with any `2xx` within 15 seconds. Anything else is retried, about 3 days in all:

* immediately, then after 5 seconds, 5 minutes, 30 minutes, 2, 5, 10, 14, 20 and 24 hours (each
  with some jitter);
* a `Retry-After` on a `429` or `503` is honoured, up to 1 hour;
* a redirect is never followed, and counts as a failure;
* after the tenth attempt the delivery gives up (`dead`). You can retry it from the log.

If an endpoint answers **`410 Gone`**, it is switched off at once. If every delivery fails for a
day, your owners and admins get an email; after **5 days** of failures the endpoint is switched off,
they are emailed again, and your other endpoints receive `webhook_endpoint.disabled`.

Turning an endpoint back on is up to you (`PATCH /v1/webhook_endpoints/{id}` with
`"status": "enabled"`, or **Turn on** in HQ). Then replay what it missed.

## 5. The delivery log, retries and replays [#5-the-delivery-log-retries-and-replays]

```bash
# what happened
curl https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_…/deliveries \
  -H "Authorization: Bearer $HQ_API_KEY"

# send one again (same webhook-id)
curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_deliveries/whd_…/retry \
  -H "Authorization: Bearer $HQ_API_KEY"

# send everything from a window again (at most 30 days back); returns an operation
curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_…/replay \
  -H "Authorization: Bearer $HQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "since": "2026-11-02T00:00:00Z", "types": ["session.*"] }'
```

The log keeps 30 days: every attempt's status code, time and error, and up to 4 KiB of what your
receiver answered last. Events are kept 30 days too, and `GET /v1/events` lists them. An event is
recorded only while an endpoint subscribes to its type.

## 6. Roll the secret [#6-roll-the-secret]

```bash
curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_…/rotate_secret \
  -H "Authorization: Bearer $HQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "previous_secret_expires_in": 86400 }'
```

The new `secret` is shown once. For `previous_secret_expires_in` seconds (up to 7 days; `0` ends it
now) every delivery carries both signatures, so you can update your receiver without missing one.

## Sending addresses [#sending-addresses]

Deliveries come from Google Cloud addresses that can change, so there is no fixed list to allowlist
yet: the signature is what proves a request is from HQ. Ask us if you need fixed addresses.
