> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.apologist.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.apologist.ai/_mcp/server.

# Chat Completion Events

POST 

Sent by the Apologist Agent platform to your configured webhook URL whenever a subscribed agent event occurs. Your endpoint must respond with any 2xx status to acknowledge; non-2xx responses are logged and are **not** retried.

Verify the request before trusting it. Two security modes are supported per notification:

- **Signature mode** (recommended): `X-Webhook-Signature` carries
  `sha256=<hex>`, the HMAC-SHA256 of `"{X-Webhook-Timestamp}.{rawBody}"`
  keyed by your secret. Reject stale timestamps and compare in constant
  time.

- **Shared-secret mode**: `X-Webhook-Secret` carries the plaintext
  secret to compare against your stored value.


See WEBHOOKS.md for full verification examples.

Reference: https://docs.apologist.ai/agent-api/api-reference/webhooks/receive-agent-webhook

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.0
info:
  title: agent-api
  version: 1.0.0
paths: {}
webhooks:
  subpackage_webhooks.receiveAgentWebhook:
    post:
      operationId: subpackage_webhooks.receiveAgentWebhook
      summary: Chat Completion Events
      description: >-
        Sent by the Apologist Agent platform to your configured webhook URL
        whenever a subscribed agent event occurs. Your endpoint must respond
        with any 2xx status to acknowledge; non-2xx responses are logged and are
        **not** retried.


        Verify the request before trusting it. Two security modes are supported
        per notification:


        - **Signature mode** (recommended): `X-Webhook-Signature` carries
          `sha256=<hex>`, the HMAC-SHA256 of `"{X-Webhook-Timestamp}.{rawBody}"`
          keyed by your secret. Reject stale timestamps and compare in constant
          time.

        - **Shared-secret mode**: `X-Webhook-Secret` carries the plaintext
          secret to compare against your stored value.


        See WEBHOOKS.md for full verification examples.
      parameters:
        - name: X-Webhook-Signature
          in: header
          description: >-
            Signature mode only. `sha256=<hex>` HMAC-SHA256 of
            "{timestamp}.{rawBody}" keyed by the notification secret.
          required: false
          schema:
            type: string
        - name: X-Webhook-Timestamp
          in: header
          description: >-
            Signature mode only. Unix time in seconds when the request was
            signed.
          required: false
          schema:
            type: string
        - name: X-Webhook-Secret
          in: header
          description: Shared-secret mode only. The plaintext shared secret.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayload'
components:
  schemas:
    WebhookNotificationRef:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
      required:
        - id
        - name
      description: The notification configuration that produced this delivery.
      title: WebhookNotificationRef
    WebhookEventInfoKey:
      type: string
      enum:
        - prompt_submit
        - response_start
        - response_end
        - automations_end
        - response_like
        - response_flag
        - response_feedback
        - referral_click
        - cta_trigger
        - cta_click
        - guardrail_trigger
        - attribution_click
        - footer_click
        - new_user
        - new_device
        - new_session
        - new_conversation
        - error
      description: Stable machine-readable event key.
      title: WebhookEventInfoKey
    WebhookEventInfo:
      type: object
      properties:
        key:
          $ref: '#/components/schemas/WebhookEventInfoKey'
          description: Stable machine-readable event key.
        label:
          type: string
          description: Human-readable event label.
        occurred_at:
          type: string
          format: date-time
      required:
        - key
        - label
        - occurred_at
      title: WebhookEventInfo
    WebhookAgentRef:
      type: object
      properties:
        id:
          type: integer
        name:
          type:
            - string
            - 'null'
      required:
        - id
      title: WebhookAgentRef
    WebhookNamedRef:
      type: object
      properties:
        id:
          type: integer
        name:
          type:
            - string
            - 'null'
      required:
        - id
      title: WebhookNamedRef
    WebhookCta:
      type: object
      properties:
        id:
          type: integer
        name:
          type:
            - string
            - 'null'
        content:
          type:
            - string
            - 'null'
      required:
        - id
      title: WebhookCta
    WebhookEvaluation:
      type: object
      properties:
        score:
          type:
            - number
            - 'null'
          format: double
        passed:
          type:
            - boolean
            - 'null'
        content:
          type:
            - string
            - 'null'
      description: Result of an evaluation run for CTA/guardrail events.
      title: WebhookEvaluation
    WebhookPayload:
      type: object
      properties:
        notification:
          $ref: '#/components/schemas/WebhookNotificationRef'
        event:
          $ref: '#/components/schemas/WebhookEventInfo'
        agent:
          $ref: '#/components/schemas/WebhookAgentRef'
        completion:
          type:
            - object
            - 'null'
          additionalProperties:
            description: Any type
          description: >-
            Present when the event is tied to a prompt. Includes the prompt and
            response plus `automations` and `tags` arrays. Shape mirrors the
            prompt API object.
        channel:
          $ref: '#/components/schemas/WebhookNamedRef'
          description: Present when the prompt arrived via a channel.
        platform:
          $ref: '#/components/schemas/WebhookNamedRef'
          description: Present alongside `channel` when the channel has a platform.
        cta:
          $ref: '#/components/schemas/WebhookCta'
          description: Present for cta_trigger and cta_click events.
        guardrail:
          $ref: '#/components/schemas/WebhookNamedRef'
          description: Present for guardrail_trigger events.
        evaluator:
          $ref: '#/components/schemas/WebhookNamedRef'
          description: Present for CTA/guardrail events that ran an evaluation.
        evaluation:
          $ref: '#/components/schemas/WebhookEvaluation'
      required:
        - notification
        - event
        - agent
      description: >-
        Canonical JSON body POSTed to a configured webhook URL. `notification`,
        `event`, and `agent` are always present; the remaining sections appear
        only when relevant to the event. Treat the payload as additive and
        ignore unrecognised fields.
      title: WebhookPayload

```