# Webhooks

Signed HTTPS callbacks for your organization's events, their delivery log, retries and replays, and the events list. Verify every delivery with a Standard Webhooks library.



{/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */}

<ApiEndpoint>
  <ApiEndpointMain>
    ## List webhook endpoints [#list-webhook-endpoints]

    <ApiEndpointHeader method="GET" path="/v1/webhook_endpoints" scope="webhooks:read" />

    Newest first. A secret is never returned; `secret_prefixes` names the ones that sign.

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="ending_before" type="string">
        Return objects newer than this id (the previous page).
      </ApiParam>

      <ApiParam name="status" type="string">
        Only endpoints in this state. One of `enabled`, `disabled`, `auto_disabled`.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [WebhookEndpoint](#webhookendpoint) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of webhook endpoints.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/webhook_endpoints \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/webhook_endpoints",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "webhook_endpoint",
          "id": "we_CTJtkIwMC3hOmcKEGLjbN8",
          "url": "https://hooks.example.com/hq",
          "description": "Ops alerts",
          "enabled_events": ["operation.failed", "session.*"],
          "team_ids": null,
          "include_message_text": false,
          "api_version": "2026-11-01",
          "status": "enabled",
          "disabled_reason": null,
          "failing_since": null,
          "last_success_at": "2026-10-14T16:05:34.000Z",
          "secret_prefixes": ["whsec_MfKQ"],
          "created_at": "2026-10-02T12:00:00.000Z",
          "updated_at": "2026-10-02T12:00:00.000Z"
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Create a webhook endpoint [#create-a-webhook-endpoint]

    <ApiEndpointHeader method="POST" path="/v1/webhook_endpoints" scope="webhooks:manage" />

    The URL must be `https`, on port 443 or 8443, with a host name that resolves only to public
    addresses (`422 host_not_allowed` otherwise, also when the name does not resolve). The
    response carries the signing `secret` ONCE: store it now. Every owner and
    admin of the organization is emailed. A trial organization cannot create endpoints.

    A retry with the same `Idempotency-Key` answers `201` with the same endpoint, without
    `secret` and with `secret_omitted: true` (the secret is never stored for a replay). If the
    first answer was lost, roll the secret (`POST …/rotate_secret`).

    A key restricted to some AI teams cannot do this (403 team_restricted).

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="url" type="string" required="true" />

      <ApiParam name="description" type="string" />

      <ApiParam name="enabled_events" type="array of string" required="true" />

      <ApiParam name="team_ids" type="array of string or null" />

      <ApiParam name="include_message_text" type="boolean">
        Send the message text in event bodies. Turning it on needs `sessions:chat.read` in the key's scopes AND held for every AI team by the key's member (a service key: its role); `403 permission_denied` otherwise.
      </ApiParam>
    </ApiParams>

    **Returns** a [WebhookEndpointWithSecret](#webhookendpointwithsecret) object.

    <ApiParams title="Responses">
      <ApiParam name="201">
        The endpoint, with its signing secret (shown once).
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{
            "url": "https://hooks.example.com/hq",
            "enabled_events": ["operation.failed", "session.*"]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            url: 'https://hooks.example.com/hq',
            enabled_events: ['operation.failed', 'session.*'],
          }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/webhook_endpoints",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={
                "url": "https://hooks.example.com/hq",
                "enabled_events": ["operation.failed", "session.*"],
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 201"
    {
      "object": "webhook_endpoint",
      "id": "we_CTJtkIwMC3hOmcKEGLjbN8",
      "url": "https://hooks.example.com/hq",
      "description": "Ops alerts",
      "enabled_events": ["operation.failed", "session.*"],
      "team_ids": null,
      "include_message_text": false,
      "api_version": "2026-11-01",
      "status": "enabled",
      "disabled_reason": null,
      "failing_since": null,
      "last_success_at": "2026-10-14T16:05:34.000Z",
      "secret_prefixes": ["whsec_MfKQ"],
      "created_at": "2026-10-02T12:00:00.000Z",
      "updated_at": "2026-10-02T12:00:00.000Z",
      "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwXc4tB1vN",
      "secret_omitted": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get a webhook endpoint [#get-a-webhook-endpoint]

    <ApiEndpointHeader method="GET" path="/v1/webhook_endpoints/{webhook_endpoint_id}" scope="webhooks:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="webhook_endpoint_id" type="string" required="true">
        A webhook endpoint id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [WebhookEndpoint](#webhookendpoint) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The endpoint.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8 \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "webhook_endpoint",
      "id": "we_CTJtkIwMC3hOmcKEGLjbN8",
      "url": "https://hooks.example.com/hq",
      "description": "Ops alerts",
      "enabled_events": ["operation.failed", "session.*"],
      "team_ids": null,
      "include_message_text": false,
      "api_version": "2026-11-01",
      "status": "enabled",
      "disabled_reason": null,
      "failing_since": null,
      "last_success_at": "2026-10-14T16:05:34.000Z",
      "secret_prefixes": ["whsec_MfKQ"],
      "created_at": "2026-10-02T12:00:00.000Z",
      "updated_at": "2026-10-02T12:00:00.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Update a webhook endpoint [#update-a-webhook-endpoint]

    <ApiEndpointHeader method="PATCH" path="/v1/webhook_endpoints/{webhook_endpoint_id}" scope="webhooks:manage" />

    Change the URL, the subscriptions, the team filter or the description, or turn the
    endpoint off (`status: disabled`) and back on (`status: enabled`, which ends a failure
    run). A new URL is checked like a new endpoint, and the admins are emailed.

    A key restricted to some AI teams cannot do this (403 team_restricted).

    <ApiParams title="Path parameters">
      <ApiParam name="webhook_endpoint_id" type="string" required="true">
        A webhook endpoint id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="url" type="string" />

      <ApiParam name="description" type="string or null" />

      <ApiParam name="enabled_events" type="array of string" />

      <ApiParam name="team_ids" type="array of string or null" />

      <ApiParam name="include_message_text" type="boolean">
        Send the message text in event bodies. Turning it on needs `sessions:chat.read` in the key's scopes AND held for every AI team by the key's member (a service key: its role); `403 permission_denied` otherwise.
      </ApiParam>

      <ApiParam name="status" type="string">
        One of `enabled`, `disabled`.
      </ApiParam>
    </ApiParams>

    **Returns** a [WebhookEndpoint](#webhookendpoint) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The endpoint.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X PATCH https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8 \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{
            "enabled_events": ["operation.failed", "session.*", "schedule.*"]
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8', {
          method: 'PATCH',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ enabled_events: ['operation.failed', 'session.*', 'schedule.*'] }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.patch(
            "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"enabled_events": ["operation.failed", "session.*", "schedule.*"]},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "webhook_endpoint",
      "id": "we_CTJtkIwMC3hOmcKEGLjbN8",
      "url": "https://hooks.example.com/hq",
      "description": "Ops alerts",
      "enabled_events": ["operation.failed", "session.*"],
      "team_ids": null,
      "include_message_text": false,
      "api_version": "2026-11-01",
      "status": "enabled",
      "disabled_reason": null,
      "failing_since": null,
      "last_success_at": "2026-10-14T16:05:34.000Z",
      "secret_prefixes": ["whsec_MfKQ"],
      "created_at": "2026-10-02T12:00:00.000Z",
      "updated_at": "2026-10-02T12:00:00.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Delete a webhook endpoint [#delete-a-webhook-endpoint]

    <ApiEndpointHeader method="DELETE" path="/v1/webhook_endpoints/{webhook_endpoint_id}" scope="webhooks:manage" />

    Its secrets and its delivery log go with it.

    A key restricted to some AI teams cannot do this (403 team_restricted).

    <ApiParams title="Path parameters">
      <ApiParam name="webhook_endpoint_id" type="string" required="true">
        A webhook endpoint id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Responses">
      <ApiParam name="200">
        Deleted.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X DELETE https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8 \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8', {
          method: 'DELETE',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.delete(
            "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "webhook_endpoint",
      "id": "we_CTJtkIwMC3hOmcKEGLjbN8",
      "deleted": true
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Roll the signing secret [#roll-the-signing-secret]

    <ApiEndpointHeader method="POST" path="/v1/webhook_endpoints/{webhook_endpoint_id}/rotate_secret" scope="webhooks:manage" />

    A new secret, shown ONCE. The old one keeps signing for `previous_secret_expires_in`
    seconds (default 86400, at most 604800; 0 stops it now), so deliveries carry two
    `v1,` signatures until it expires.

    A key restricted to some AI teams cannot do this (403 team_restricted).

    <ApiParams title="Path parameters">
      <ApiParam name="webhook_endpoint_id" type="string" required="true">
        A webhook endpoint id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="previous_secret_expires_in" type="integer" />
    </ApiParams>

    <ApiParams title="Responses">
      <ApiParam name="200">
        The endpoint, with its new signing secret (shown once).
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/rotate_secret \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"previous_secret_expires_in":86400}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/rotate_secret', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ previous_secret_expires_in: 86400 }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/rotate_secret",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"previous_secret_expires_in": 86400},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "webhook_endpoint",
      "id": "we_CTJtkIwMC3hOmcKEGLjbN8",
      "url": "https://hooks.example.com/hq",
      "description": "Ops alerts",
      "enabled_events": ["operation.failed", "session.*"],
      "team_ids": null,
      "include_message_text": false,
      "api_version": "2026-11-01",
      "status": "enabled",
      "disabled_reason": null,
      "failing_since": null,
      "last_success_at": "2026-10-14T16:05:34.000Z",
      "secret_prefixes": ["whsec_MfKQ"],
      "created_at": "2026-10-02T12:00:00.000Z",
      "updated_at": "2026-10-02T12:00:00.000Z",
      "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwXc4tB1vN",
      "secret_omitted": false,
      "previous_secret_expires_in": 86400
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Send a test event [#send-a-test-event]

    <ApiEndpointHeader method="POST" path="/v1/webhook_endpoints/{webhook_endpoint_id}/test" scope="webhooks:manage" />

    Sends `webhook.test` to this endpoint only. The delivery shows in its log.

    A key restricted to some AI teams cannot do this (403 team_restricted).

    <ApiParams title="Path parameters">
      <ApiParam name="webhook_endpoint_id" type="string" required="true">
        A webhook endpoint id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [WebhookDelivery](#webhookdelivery) object.

    <ApiParams title="Responses">
      <ApiParam name="202">
        The queued delivery.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/test \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/test', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/test",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 202"
    {
      "object": "webhook_delivery",
      "id": "whd_HK1MFIerlfCsPIS4tzvsJI",
      "endpoint_id": "we_CTJtkIwMC3hOmcKEGLjbN8",
      "event": {
        "id": "evt_9OvoJuvytSGhqe71vQ9tqx",
        "type": "session.turn.completed"
      },
      "status": "succeeded",
      "attempt_count": 1,
      "next_attempt_at": null,
      "last_attempt_at": "2026-10-14T16:05:34.000Z",
      "last_response_status": 200,
      "last_error_code": null,
      "last_latency_ms": 184,
      "replay_of": null,
      "succeeded_at": "2026-10-14T16:05:34.000Z",
      "created_at": "2026-10-14T16:05:33.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Replay events to an endpoint [#replay-events-to-an-endpoint]

    <ApiEndpointHeader method="POST" path="/v1/webhook_endpoints/{webhook_endpoint_id}/replay" scope="webhooks:manage" />

    Re-sends the events of a window (at most 30 days back) as new deliveries with their original
    `webhook-id`. Returns an operation; one replay per endpoint at a time.

    A key restricted to some AI teams cannot do this (403 team_restricted).

    <ApiParams title="Path parameters">
      <ApiParam name="webhook_endpoint_id" type="string" required="true">
        A webhook endpoint id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="since" type="string (date-time)" required="true" />

      <ApiParam name="until" type="string (date-time)">
        Default now.
      </ApiParam>

      <ApiParam name="types" type="array of string">
        Event types or namespaces (`session.*`). Default the endpoint's subscriptions.
      </ApiParam>
    </ApiParams>

    **Returns** a [Operation](#operation) object.

    <ApiParams title="Responses">
      <ApiParam name="202">
        The operation that tracks the replay.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/replay \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"since":"2026-10-13T00:00:00.000Z"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/replay', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ since: '2026-10-13T00:00:00.000Z' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/replay",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"since": "2026-10-13T00:00:00.000Z"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 202"
    {
      "object": "operation",
      "id": "op_pgDHKopuDeR6aX2GPYNtx5",
      "kind": "webhook_endpoint.replay",
      "status": "running",
      "target": {
        "type": "webhook_endpoint",
        "id": "we_CTJtkIwMC3hOmcKEGLjbN8"
      },
      "requested": {
        "since": "2026-10-13T00:00:00.000Z"
      },
      "error": null,
      "created_by": {
        "kind": "service_key",
        "key": "key_ff7QejQ24AGmu5tv2IXIdw",
        "label": "CI deploy bot"
      },
      "created_at": "2026-10-14T16:10:00.000Z",
      "updated_at": "2026-10-14T16:10:00.000Z",
      "completed_at": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## List an endpoint's deliveries [#list-an-endpoints-deliveries]

    <ApiEndpointHeader method="GET" path="/v1/webhook_endpoints/{webhook_endpoint_id}/deliveries" scope="webhooks:read" />

    The delivery log, newest first, for 30 days.

    <ApiParams title="Path parameters">
      <ApiParam name="webhook_endpoint_id" type="string" required="true">
        A webhook endpoint id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="ending_before" type="string">
        Return objects newer than this id (the previous page).
      </ApiParam>

      <ApiParam name="status" type="string">
        Only deliveries in this state. One of `pending`, `sending`, `succeeded`, `failed`, `dead`.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [WebhookDelivery](#webhookdelivery) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of deliveries.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/deliveries \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/deliveries', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/deliveries",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "webhook_delivery",
          "id": "whd_HK1MFIerlfCsPIS4tzvsJI",
          "endpoint_id": "we_CTJtkIwMC3hOmcKEGLjbN8",
          "event": {
            "id": "evt_9OvoJuvytSGhqe71vQ9tqx",
            "type": "session.turn.completed"
          },
          "status": "succeeded",
          "attempt_count": 1,
          "next_attempt_at": null,
          "last_attempt_at": "2026-10-14T16:05:34.000Z",
          "last_response_status": 200,
          "last_error_code": null,
          "last_latency_ms": 184,
          "replay_of": null,
          "succeeded_at": "2026-10-14T16:05:34.000Z",
          "created_at": "2026-10-14T16:05:33.000Z"
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get a delivery [#get-a-delivery]

    <ApiEndpointHeader method="GET" path="/v1/webhook_endpoints/{webhook_endpoint_id}/deliveries/{webhook_delivery_id}" scope="webhooks:read" />

    With every attempt and up to 4 KiB of the receiver's last response.

    <ApiParams title="Path parameters">
      <ApiParam name="webhook_endpoint_id" type="string" required="true">
        A webhook endpoint id.
      </ApiParam>

      <ApiParam name="webhook_delivery_id" type="string" required="true">
        A webhook delivery id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [WebhookDeliveryDetail](#webhookdeliverydetail) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The delivery.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/deliveries/whd_HK1MFIerlfCsPIS4tzvsJI \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/deliveries/whd_HK1MFIerlfCsPIS4tzvsJI', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/webhook_endpoints/we_CTJtkIwMC3hOmcKEGLjbN8/deliveries/whd_HK1MFIerlfCsPIS4tzvsJI",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "webhook_delivery",
      "id": "whd_HK1MFIerlfCsPIS4tzvsJI",
      "endpoint_id": "we_CTJtkIwMC3hOmcKEGLjbN8",
      "event": {
        "id": "evt_9OvoJuvytSGhqe71vQ9tqx",
        "type": "session.turn.completed"
      },
      "status": "succeeded",
      "attempt_count": 1,
      "next_attempt_at": null,
      "last_attempt_at": "2026-10-14T16:05:34.000Z",
      "last_response_status": 200,
      "last_error_code": null,
      "last_latency_ms": 184,
      "replay_of": null,
      "succeeded_at": "2026-10-14T16:05:34.000Z",
      "created_at": "2026-10-14T16:05:33.000Z",
      "last_response_snippet": "{\"ok\":true}",
      "attempts": [
        {
          "at": "2026-10-14T16:05:34.000Z",
          "status": 200,
          "latency_ms": 184,
          "error_code": null
        }
      ]
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Retry a delivery [#retry-a-delivery]

    <ApiEndpointHeader method="POST" path="/v1/webhook_deliveries/{webhook_delivery_id}/retry" scope="webhooks:manage" />

    A new delivery of the same event (the same `webhook-id`), due now.

    A key restricted to some AI teams cannot do this (403 team_restricted).

    <ApiParams title="Path parameters">
      <ApiParam name="webhook_delivery_id" type="string" required="true">
        A webhook delivery id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [WebhookDelivery](#webhookdelivery) object.

    <ApiParams title="Responses">
      <ApiParam name="202">
        The new delivery.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/webhook_deliveries/whd_HK1MFIerlfCsPIS4tzvsJI/retry \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/webhook_deliveries/whd_HK1MFIerlfCsPIS4tzvsJI/retry', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/webhook_deliveries/whd_HK1MFIerlfCsPIS4tzvsJI/retry",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 202"
    {
      "object": "webhook_delivery",
      "id": "whd_HK1MFIerlfCsPIS4tzvsJI",
      "endpoint_id": "we_CTJtkIwMC3hOmcKEGLjbN8",
      "event": {
        "id": "evt_9OvoJuvytSGhqe71vQ9tqx",
        "type": "session.turn.completed"
      },
      "status": "succeeded",
      "attempt_count": 1,
      "next_attempt_at": null,
      "last_attempt_at": "2026-10-14T16:05:34.000Z",
      "last_response_status": 200,
      "last_error_code": null,
      "last_latency_ms": 184,
      "replay_of": null,
      "succeeded_at": "2026-10-14T16:05:34.000Z",
      "created_at": "2026-10-14T16:05:33.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## List events [#list-events]

    <ApiEndpointHeader method="GET" path="/v1/events" scope="webhooks:read" />

    The organization's events of the last 30 days, newest first. An event is recorded only
    while an endpoint subscribes to its type.

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="ending_before" type="string">
        Return objects newer than this id (the previous page).
      </ApiParam>

      <ApiParam name="type" type="string">
        An event type, or a namespace such as `session.*`.
      </ApiParam>

      <ApiParam name="created[gte]" type="string (date-time)" />

      <ApiParam name="created[lte]" type="string (date-time)" />
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [Event](#event) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of events.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/events \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/events', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/events",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "id": "evt_9OvoJuvytSGhqe71vQ9tqx",
          "object": "event",
          "type": "session.turn.completed",
          "api_version": "2026-11-01",
          "created_at": "2026-10-14T16:05:33.000Z",
          "org_id": "org_3SvwLF4ulih8bHz5KtmNOO",
          "team_id": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
          "resource": {
            "type": "session",
            "id": "sess_0a843Y2wTmED2k3FJPP56X"
          },
          "data": {
            "session_id": "sess_0a843Y2wTmED2k3FJPP56X"
          }
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get an event [#get-an-event]

    <ApiEndpointHeader method="GET" path="/v1/events/{event_id}" scope="webhooks:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="event_id" type="string" required="true">
        An event id (the `webhook-id` of its deliveries).
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Event](#event) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The event.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/events/evt_9OvoJuvytSGhqe71vQ9tqx \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/events/evt_9OvoJuvytSGhqe71vQ9tqx', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/events/evt_9OvoJuvytSGhqe71vQ9tqx",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "id": "evt_9OvoJuvytSGhqe71vQ9tqx",
      "object": "event",
      "type": "session.turn.completed",
      "api_version": "2026-11-01",
      "created_at": "2026-10-14T16:05:33.000Z",
      "org_id": "org_3SvwLF4ulih8bHz5KtmNOO",
      "team_id": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "resource": {
        "type": "session",
        "id": "sess_0a843Y2wTmED2k3FJPP56X"
      },
      "data": {
        "session_id": "sess_0a843Y2wTmED2k3FJPP56X"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### WebhookEndpoint [#webhookendpoint]

    A URL that receives your organization's events, signed (Standard Webhooks v1).

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="url" type="string" />

      <ApiParam name="description" type="string or null" />

      <ApiParam name="enabled_events" type="array of string">
        Event types and namespaces (`session.*`) this endpoint receives.
      </ApiParam>

      <ApiParam name="team_ids" type="array of string or null">
        Only events of these AI teams (organization events always pass). Null is every team. A key restricted to some AI teams sees only its own teams here, and does not see an endpoint limited to other teams at all.
      </ApiParam>

      <ApiParam name="include_message_text" type="boolean">
        Event bodies carry the message text.
      </ApiParam>

      <ApiParam name="api_version" type="string">
        The version event bodies are rendered at, pinned at creation.
      </ApiParam>

      <ApiParam name="status" type="string">
        One of `enabled`, `disabled`, `auto_disabled`.
      </ApiParam>

      <ApiParam name="disabled_reason" type="string or null">
        One of `manual`, `gone_410`, `continuous_failure`, `null`.
      </ApiParam>

      <ApiParam name="failing_since" type="string or null" />

      <ApiParam name="last_success_at" type="string or null" />

      <ApiParam name="secret_prefixes" type="array of string">
        The display prefixes of the secrets that sign right now (two during a rotation).
      </ApiParam>

      <ApiParam name="created_at" type="string (date-time)" />

      <ApiParam name="updated_at" type="string (date-time)" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The WebhookEndpoint object"
    {
      "object": "webhook_endpoint",
      "id": "we_CTJtkIwMC3hOmcKEGLjbN8",
      "url": "https://hooks.example.com/hq",
      "description": "Ops alerts",
      "enabled_events": ["operation.failed", "session.*"],
      "team_ids": null,
      "include_message_text": false,
      "api_version": "2026-11-01",
      "status": "enabled",
      "disabled_reason": null,
      "failing_since": null,
      "last_success_at": "2026-10-14T16:05:34.000Z",
      "secret_prefixes": ["whsec_MfKQ"],
      "created_at": "2026-10-02T12:00:00.000Z",
      "updated_at": "2026-10-02T12:00:00.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### WebhookEndpointWithSecret [#webhookendpointwithsecret]

    <ApiParams title="Attributes" />
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The WebhookEndpointWithSecret object"
    {
      "object": "webhook_endpoint",
      "id": "we_CTJtkIwMC3hOmcKEGLjbN8",
      "url": "https://hooks.example.com/hq",
      "description": "Ops alerts",
      "enabled_events": ["operation.failed", "session.*"],
      "team_ids": null,
      "include_message_text": false,
      "api_version": "2026-11-01",
      "status": "enabled",
      "disabled_reason": null,
      "failing_since": null,
      "last_success_at": "2026-10-14T16:05:34.000Z",
      "secret_prefixes": ["whsec_MfKQ"],
      "created_at": "2026-10-02T12:00:00.000Z",
      "updated_at": "2026-10-02T12:00:00.000Z",
      "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwXc4tB1vN",
      "secret_omitted": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### WebhookDelivery [#webhookdelivery]

    One event sent (or to be sent) to one endpoint, with its retries.

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="endpoint_id" type="string" />

      <ApiParam name="event" type="object" />

      <ApiParam name="status" type="string">
        One of `pending`, `sending`, `succeeded`, `failed`, `dead`.
      </ApiParam>

      <ApiParam name="attempt_count" type="integer" />

      <ApiParam name="next_attempt_at" type="string or null" />

      <ApiParam name="last_attempt_at" type="string or null" />

      <ApiParam name="last_response_status" type="integer or null" />

      <ApiParam name="last_error_code" type="string or null" />

      <ApiParam name="last_latency_ms" type="integer or null" />

      <ApiParam name="replay_of" type="string or null" />

      <ApiParam name="succeeded_at" type="string or null" />

      <ApiParam name="created_at" type="string (date-time)" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The WebhookDelivery object"
    {
      "object": "webhook_delivery",
      "id": "whd_HK1MFIerlfCsPIS4tzvsJI",
      "endpoint_id": "we_CTJtkIwMC3hOmcKEGLjbN8",
      "event": {
        "id": "evt_9OvoJuvytSGhqe71vQ9tqx",
        "type": "session.turn.completed"
      },
      "status": "succeeded",
      "attempt_count": 1,
      "next_attempt_at": null,
      "last_attempt_at": "2026-10-14T16:05:34.000Z",
      "last_response_status": 200,
      "last_error_code": null,
      "last_latency_ms": 184,
      "replay_of": null,
      "succeeded_at": "2026-10-14T16:05:34.000Z",
      "created_at": "2026-10-14T16:05:33.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### Operation [#operation]

    A change the reconcilers carry out. It settles as succeeded or failed.

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="kind" type="string">
        Open-ended: computer.start, computer.stop, computer.update, computer.resize, webhook_endpoint.replay.
      </ApiParam>

      <ApiParam name="status" type="string">
        running, succeeded or failed.
      </ApiParam>

      <ApiParam name="target" type="object" />

      <ApiParam name="requested" type="object" />

      <ApiParam name="error" type="object or null" />

      <ApiParam name="created_by" type="object" />

      <ApiParam name="created_at" type="string (date-time)" />

      <ApiParam name="updated_at" type="string (date-time)" />

      <ApiParam name="completed_at" type="string or null" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Operation object"
    {
      "object": "operation",
      "id": "op_pgDHKopuDeR6aX2GPYNtx5",
      "kind": "computer.resize",
      "status": "running",
      "target": {
        "type": "team",
        "id": "team_3kQ9vX2mR8tLpZ4wYc1aBd"
      },
      "requested": {
        "tier": "boost"
      },
      "error": null,
      "created_by": {
        "kind": "service_key",
        "key": "key_ff7QejQ24AGmu5tv2IXIdw",
        "label": "CI deploy bot"
      },
      "created_at": "2026-10-14T16:10:00.000Z",
      "updated_at": "2026-10-14T16:10:04.000Z",
      "completed_at": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### WebhookDeliveryDetail [#webhookdeliverydetail]

    <ApiParams title="Attributes" />
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The WebhookDeliveryDetail object"
    {
      "object": "webhook_delivery",
      "id": "whd_HK1MFIerlfCsPIS4tzvsJI",
      "endpoint_id": "we_CTJtkIwMC3hOmcKEGLjbN8",
      "event": {
        "id": "evt_9OvoJuvytSGhqe71vQ9tqx",
        "type": "session.turn.completed"
      },
      "status": "succeeded",
      "attempt_count": 1,
      "next_attempt_at": null,
      "last_attempt_at": "2026-10-14T16:05:34.000Z",
      "last_response_status": 200,
      "last_error_code": null,
      "last_latency_ms": 184,
      "replay_of": null,
      "succeeded_at": "2026-10-14T16:05:34.000Z",
      "created_at": "2026-10-14T16:05:33.000Z",
      "last_response_snippet": "{\"ok\":true}",
      "attempts": [
        {
          "at": "2026-10-14T16:05:34.000Z",
          "status": 200,
          "latency_ms": 184,
          "error_code": null
        }
      ]
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### Event [#event]

    One event, on a session's stream, in a webhook delivery's body, and in the events list.

    <ApiParams title="Attributes">
      <ApiParam name="id" type="string" required="true">
        Stable across reconnects. Deduplicate on it.
      </ApiParam>

      <ApiParam name="object" type="string" required="true" />

      <ApiParam name="type" type="string" required="true" />

      <ApiParam name="api_version" type="string" required="true" />

      <ApiParam name="created_at" type="string (date-time)" required="true" />

      <ApiParam name="org_id" type="string" required="true" />

      <ApiParam name="team_id" type="string" />

      <ApiParam name="resource" type="object" required="true" />

      <ApiParam name="data" type="object" required="true" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Event object"
    {
      "id": "evt_9OvoJuvytSGhqe71vQ9tqx",
      "object": "event",
      "type": "session.turn.completed",
      "api_version": "2026-11-01",
      "created_at": "2026-10-14T16:05:33.000Z",
      "org_id": "org_3SvwLF4ulih8bHz5KtmNOO",
      "team_id": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "resource": {
        "type": "session",
        "id": "sess_0a843Y2wTmED2k3FJPP56X"
      },
      "data": {
        "session_id": "sess_0a843Y2wTmED2k3FJPP56X"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
