How to Register for Webhooks (Incoming Messages)

Subscribe to be notified when new messages are posted to a channel.

POST /apps/subscribe
Content-Type: application/json

{
  "subscriptions": ["message.posted.to.channel"],
  "subscription_filters": [
    {
      "key": "creator_id",
      "value": "<your_user_guid>",
      "operator": "ne"
    }
  ]
}

The creator_id + ne filter excludes messages you sent yourself, preventing infinite reply loops. Get your user_guid from GET /whoami.

To accept only messages from a specific user, use creator_id + eq.

Common events to register to receive are:

event	description
`message.voicememo.created`	A new voice memo was recorded
`ai.prompt.response.generated`	A response was generated from a built in AI prompt
`action-item.created`	An action item was created

Full list of events can be found in the webhook events documentation.

Available filter options:

key	operator	description
`workspace_ids`	`eq`	Limit to a specific workspace
`channel_ids`	`eq`	Limit to a specific conversation
`creator_id`	`ne`	Exclude messages from a specific user
`creator_id`	`eq`	Only receive messages from a specific user

Note filters apply to all events in the given registration, which can result in no matches if you are not careful with matching types. Consider creating separate registrations for different event types if you need different filters. Processing webhook payloads: Use the transcript_txt field as the body of the message.

For full structure of webhook payloads, see the cv-contracts repository: https://github.com/PhononX/cv-contracts/tree/main/src/schemas/webhook

To update or unsubscribe from webhooks, see how-to-update-or-unsubscribe-a-webhook.md.