# Webhook events

Betterstood sends four versioned CloudEvents 1.0 structured JSON messages through the same verified HTTPS endpoint and delivery system.

An endpoint can subscribe to any subset of exactly three lifecycle event types, including none
when it is registered only as a conditional-automation destination:

- `com.elicitra.interaction.ended.v1`
- `com.elicitra.analysis.completed.v1`
- `com.elicitra.analysis.failed.v1`

The fourth public event, `com.elicitra.automation.triggered.v1`, has delivery mode `conditional_destination`. It is not subscribable. Betterstood sends it only when a scenario's conditional action matches and points to that already verified endpoint. The lifecycle subscriptions remain unconditional event feeds.

Choosing no lifecycle subscriptions does not disable the endpoint: after verification it can still
be selected by a scenario automation rule, but it receives no lifecycle feed.

The complete current contract is available as [AsyncAPI 3.0](/developers/v14/asyncapi.yaml) and individual [JSON Schemas](/developers/v14/manifest.json). Its AsyncAPI document version is `1.1.0`. Emitted lifecycle events keep their v5 `dataschema` URLs and the automation event keeps its v6 URL; v14 republishes those unchanged schemas for discovery. Event type suffixes remain `.v1`; they version each event payload protocol independently from the Developer Access contract tree.

## Endpoint verification

Create the endpoint in **Organization settings → Integrations → Developer Access**. Betterstood sends a signed, no-PII `application/json` control body with the exact shape `{ "challenge": "<random-128-bit-value>" }`. It is not a CloudEvent. Activation requires both a 2xx response and entering the challenge observed by your receiver into Betterstood.

Endpoints must use HTTPS on port 443. The destination URL is immutable; replacing it creates a new endpoint and verification flow.

## Delivery semantics

- Delivery is **at least once**. Deduplicate by CloudEvent `id` in durable storage.
- Ordering is not guaranteed. `data.lifecycleSequence` is a hint on the three lifecycle events, not a transport-order guarantee. The automation event omits it.
- Manual replay reuses the same event id so the same deduplication rule applies.

Read [Delivery, retries, deduplication, and ordering](/developers/webhooks/delivery/) for the exact schedule, response handling, replay window, event lifecycle, payload limits, and endpoint verification flow.

## Payload boundary

Events include stable Betterstood identifiers, normalized interaction state, scenario/campaign context, available respondent name/email/phone, normalized consent grants, and data-minimized analysis outputs. The automation event additionally identifies the activation execution, matched rule, and matched conditions in a fixed `activation` block.

They never include transcripts, recordings, evidence/source quotes, raw model output, provider identifiers, raw errors, debug data, or arbitrary lead-card JSON. See [Security and privacy](/developers/security/).