Webhook Events Reference

A webhook delivery is a signed HTTP POST sent to a registered destination when something happens to captured conversation data. This page documents which events exist and the exact shape of the body every delivery carries.

See also: Webhooks API to register a destination, and Verifying Webhook Signatures to confirm a delivery is genuine.

---

Delivery Semantics

• At-least-once. A destination may receive the same delivery more than once (a retry, or a redelivery after a worker restart). Use the webhook-id header (documented in the signing guide) to identify repeats and deduplicate; it is stable across every attempt of one delivery.
• No ordering guarantee between deliveries. Two deliveries for the same session, or even the same record, are not guaranteed to arrive in the order they happened.

---

Event Kinds

Kind	Fires when
data.collected	A Gnosari captures a kind of data from a conversation for the first time
data.updated	A previously captured record gains or corrects detail

A destination subscribes to one or both kinds via event_kinds on the subscription. data.collected fires exactly once per (session, data kind) pair; a later correction to the same record is a data.updated delivery, never a second data.collected.

---

Envelope Reference

Every delivery body is a JSON object with this shape:

{
  "type": "data.collected",
  "event_id": "1b6f6e2a-1234-5678-9abc-1234567890ab",
  "created_at": "2026-08-10T12:00:00Z",
  "payload_version": "v1",
  "account_id": 42,
  "agent_id": 7,
  "session_id": "sess_abc123",
  "data_kind": "Lead",
  "record_id": 1234,
  "attributes": {
    "name": "Alice Smith",
    "email": "alice@example.com"
  },
  "correlation_id": "5c8e6a10-aaaa-bbbb-cccc-1234567890ab",
  "provenance": {
    "quotes": ["My email is alice@example.com"],
    "message_ids": [981]
  }
}

Field	Type	Description
type	string	The event kind (data.collected or data.updated). Present so a destination subscribed to both kinds can route without inspecting the rest of the body
event_id	string (uuid)	Identifier of the underlying stored event
created_at	string	When the event was recorded, ISO-8601 UTC with a Z suffix, seconds precision
payload_version	string	Always v1 today. See "Versioning Policy" below
account_id	integer	The owning account
agent_id	integer	The agent whose conversation produced the record
session_id	string	The conversation session
data_kind	string	The captured entity type's name, e.g. "Lead"
record_id	integer	The captured record's ID
attributes	object	The captured field values
correlation_id	string | null	Groups every event from one extraction pass
provenance	object	ONLY present when the destination opted in via include_provenance. Absent entirely otherwise, never present-and-null

attributes is a snapshot

attributes is the value snapshot taken at capture time. If the underlying record is edited after the event fires, a retry of that SAME delivery still carries what was true at capture, not the current value. A later edit is delivered separately, as its own data.updated event.

correlation_id groups an extraction pass

A single conversation turn can capture or update several records at once. Every event produced by that pass shares the same correlation_id, so a destination can group them without guessing from timing.

provenance is opt-in

provenance carries the conversation quotes and message identifiers that justify the captured value. It is present only when the destination's include_provenance flag is true; when false (the default), the key is not present in the body at all.

---

Versioning Policy

• payload_version starts, and currently stays, at "v1".
• New OPTIONAL fields may be added within v1. A destination should ignore keys it does not recognize.
• A field RENAME, REMOVAL, or TYPE CHANGE ships as a new payload_version. Existing v1 subscribers keep receiving the v1 shape unchanged.