AI Workforce OneHQDocs

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 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

Each delivery is a POST of one event with three headers, following Standard Webhooks:

HeaderValue
webhook-idThe event id (evt_…). It stays the same across retries and replays.
webhook-timestampWhen this attempt was sent, in Unix seconds.
webhook-signaturev1,<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-Id and User-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.

TypeWhen
session.turn.completedThe reply to a prompt you sent with POST /v1/sessions/{id}/messages finished.
session.message.status_changedThat prompt moved (typing, delivered, unconfirmed, failed, …).
operation.completed, operation.failedA Cloud Computer operation or a webhook replay settled.
secret.created, secret.updated, secret.deletedA secret changed. The name and scope only.
api_key.created, api_key.revokedAn API key was created or revoked.
webhook_endpoint.disabledOne of your endpoints was switched off.
webhook.testYou 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-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

# 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.