> 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/outgoing-webhooks/receive-agent-webhook

## Request

### Headers

- `X-Webhook-Signature` (string, optional) — Signature mode only. `sha256=<hex>` HMAC-SHA256 of "\{timestamp}.\{rawBody}" keyed by the notification secret.
- `X-Webhook-Timestamp` (string, optional) — Signature mode only. Unix time in seconds when the request was signed.
- `X-Webhook-Secret` (string, optional) — Shared-secret mode only. The plaintext shared secret.

### Payload

- `notification` (object, required) — The notification configuration that produced this delivery.
  - `id` (integer, required)
  - `name` (string, required)
- `event` (object, required)
  - `key` (enum, required) — Stable machine-readable event key.
    - Allowed values: `prompt_submit`, `response_start`, `response_end`, `automation_trigger`, `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`
  - `label` (string, required) — Human-readable event label.
  - `occurred_at` (datetime, required)
- `agent` (object, required)
  - `id` (integer, required)
  - `name` (string, optional, nullable)
- `completion` (map from string to any, optional, nullable) — 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` (object, optional) — Present when the prompt arrived via a channel.
  - `id` (integer, required)
  - `name` (string, optional, nullable)
- `platform` (object, optional) — Present alongside `channel` when the channel has a platform.
  - `id` (integer, required)
  - `name` (string, optional, nullable)
- `cta` (object, optional) — Present for cta_trigger and cta_click events.
  - `id` (integer, required)
  - `name` (string, optional, nullable)
  - `content` (string, optional, nullable)
- `guardrail` (object, optional) — Present for guardrail_trigger events.
  - `id` (integer, required)
  - `name` (string, optional, nullable)
- `automation` (object, optional) — Present for automation_trigger events.
  - `id` (integer, required)
  - `name` (string, optional, nullable)
- `evaluator` (object, optional) — Present for CTA, guardrail, or automation events that ran an evaluation.
  - `id` (integer, required)
  - `name` (string, optional, nullable)
- `evaluation` (object, optional) — Result of an evaluation run for CTA, guardrail, or automation events.
  - `score` (double, optional, nullable)
  - `passed` (boolean, optional, nullable)
  - `content` (string, optional, nullable)
- `trace` (object, optional) — OpenTelemetry context for the API request that produced this event. Present when the Agent created or continued a W3C trace.
  - `trace_id` (string, optional) — 32-character hex trace id
  - `span_id` (string, optional) — 16-character hex span id