Skip to navigation
API ReferenceOutgoing Webhooks

Chat Completion Events

View as Markdown

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.

Headers

X-Webhook-SignaturestringOptional

Signature mode only. sha256=<hex> HMAC-SHA256 of “{timestamp}.{rawBody}” keyed by the notification secret.

X-Webhook-TimestampstringOptional
Signature mode only. Unix time in seconds when the request was signed.
X-Webhook-SecretstringOptional

Shared-secret mode only. The plaintext shared secret.

Payload

The payload of this webhook request is an object.
notificationobjectRequired
The notification configuration that produced this delivery.
eventobjectRequired
agentobjectRequired
completionmap from strings to any or nullOptional

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.

channelobjectOptional
Present when the prompt arrived via a channel.
platformobjectOptional

Present alongside channel when the channel has a platform.

ctaobjectOptional

Present for cta_trigger and cta_click events.

guardrailobjectOptional

Present for guardrail_trigger events.

automationobjectOptional

Present for automation_trigger events.

evaluatorobjectOptional
Present for CTA, guardrail, or automation events that ran an evaluation.
evaluationobjectOptional
Result of an evaluation run for CTA, guardrail, or automation events.
traceobjectOptional
OpenTelemetry context for the API request that produced this event. Present when the Agent created or continued a W3C trace.

Response

200
Acknowledged. Any 2xx status is treated as success.