Event reference

Quick reference

not_realtime means a delay; no_longer_realtime means not delivered. Message events are inbound only.

Delivery availability

GET /v1/webhooks/events returns the live catalogue, with an availability field:

Default and opt-in events

Omitting events on create subscribes to the source's default set:

chat.updated, chat.deleted, connection.new, step.executed, and the account.initial_sync.* events are never auto-subscribed; name them in events.

Payload structure

Every delivery shares the same outer envelope:

{
  "id":           "wdl_YOUR_DELIVERY_ID",
  "webhook_id":   "wh_YOUR_WEBHOOK_ID",
  "event":        "message.received",
  "data": {
    "account_id":  "acc_YOUR_ACCOUNT_ID",
    "event":       "message.received",
    "chat_id":     "chat_YOUR_CHAT_ID",
    "message_id":  "msg_YOUR_MESSAGE_ID",
    "text":        "Hello, how can I help?",
    "sender": {
      "name":        "Alex Jordan",
      "profile_url": "https://www.linkedin.com/in/alexjordan",
      "provider_id": "urn:li:member:123456789"
    },
    "attachments": [],
    "occurred_at": "2026-05-28T09:15:00.000Z"
  },
  "delivered_at": "2026-05-28T09:15:01.234Z"
}

id (wdl_...) changes on every retry. data always carries account_id, event, and occurred_at: deduplicate on those three. Message and connection events carry their content in data; account-status events carry state only; post events carry ids, timestamps, and a failure code, never the post text or media; Motion events carry ids and reason codes, plus the Contact record, never message text.

When an account needs re-authentication (account.reconnect_needed), the next call is POST /v1/auth/intent with its account_id.

Motion events

Seven events report what a Motion does. A motion webhook needs a non-empty account_ids, like messaging. Omit events and it gets all but step.executed, which is opt-in because of its volume.

curl -X POST https://api.curviate.com/v1/webhooks \
  -H "Authorization: Bearer cvt_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "motion",
    "request_url": "https://hooks.example.com/curviate",
    "account_ids": ["acc_YOUR_ACCOUNT_ID"],
    "motion_ids": ["mot_YOUR_MOTION_ID"]
  }'

Every data carries event and occurred_at, plus these keys. Nothing else is delivered: no message text or any text a Step rendered.

contact is your own team's Contact record, whole (id, linkedin_url, full_name, first_name, last_name, headline, job_title, company, email, location, about, extra, tags), or null once that Contact is deleted.

An event with an account_id goes to the webhooks that list that account. motion.status_changed, and an enrollment.skipped with no account yet, go once to each webhook whose account_ids overlap the Motion's sending accounts, with account_id null. Motion events are not kept in the 24-hour event log.

Filter by Motion. Every webhook, of any source, takes an optional motion_ids (up to 100 of your own mot_ ids) on create and update. When set, only events whose data.motion_id is listed are delivered; an event without a motion_id is not. Another team's id is a 400.

Motion chats. The message.* events carry motion_id and enrollment_id in data: set when the chat belongs to an Enrollment of that account, null otherwise.

Errors you may hit

Full envelope shapes are in the error reference.

Next steps

• Messaging events: full payloads for the 7 messaging events.
• User events: full payloads for the 2 connection events.
• Account status events: full payloads for all 15 account-status events.
• Post events: payloads for scheduled-post outcomes.
• Motion events: the seven motion events, motion_ids, and the Motion keys on message.*.
• Verifying signatures: validate every delivery before you process it.