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
In HQ, open Settings, Developers, Webhooks and choose Add endpoint, or call the API with a
key that holds webhooks:manage:
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"] }'{
"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
secretis shown once. Store it in your secret manager. HQ cannot show it again; if you lose it, roll it. A retry with the sameIdempotency-Keyanswers the same endpoint withoutsecret, withsecret_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_idslimits 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 inteam_idsand only the deliveries and events about its teams.include_message_text: truesends the message text in event bodies. Turning it on needs a key withsessions: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
Each delivery is a POST of one event with three headers, following
Standard Webhooks:
| 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:
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);
});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-IdandUser-Agent: AIWorkforceOne-Webhooks/1.
3. The event
The body is the same envelope GET /v1/events/{event_id} returns:
{
"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
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-Afteron a429or503is 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
# 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
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
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.