---
title: "Subscribe user to events subscribed via a Webhook"
method: POST
path: "/apps/subscribe"
tags: ["Apps"]
---

# Subscribe user to events subscribed via a Webhook

`POST /apps/subscribe`

## Request

- Base URL: `https://api.carbonvoice.app`
- URL: `https://api.carbonvoice.app/apps/subscribe`
- Auth: one of:
  - API key in header `pxtoken`
  - OAuth 2 (implicit, authorization URL `https://api.carbonvoice.app/oauth/authorize`)

Registers a webhook for the user without requiring a client_id. A client_id will be generated automatically. To update or delete, use the client_id returned in the response. Authorization matches `POST /apps/:client_id/subscribe` once the implicit client exists: OAuth access token for that client, Personal Access Token with cv:write on an app you own, short-lived stateless agent JWT (minted via `POST /agents/:id/tokens`) whose payload includes cv:read and cv:write, or session token (pxtoken) for an app you own.

## Request body

- SubscribeUserPayload
  - `subscriptions` string[]: All events are subscribed by default: message.initializing, message.started, message.paused, message.resumed, message.offline, message.processing, message.finished, message.deleted, message.discussion-notes.added, message.label.added, message.attachment.added, message.attachment.uploaded, message.posted.to.channel, message.voicememo.created, channel.created, channel.deleted, channel.user.joined, channel.users.added, channel.user.left, channel.user.removed, channel.async-check.mid, channel.async-check.ending, channel.async.ended, channel.async.extended, channel.async.shortened, channel.ai-summary.generated, workspace.user.joined, workspace.user.added, workspace.user.left, workspace.user.removed, workspace.findable-channel.created, ai.prompt.response.generated, action-item.created, action-item.updated, action-item.deleted, action-item.status.changed, ask.answered. Also supports 'schedule' trigger for time-based triggers.
  - `webhookURL` string: Webhook URL to send the data
  - `subscription_filters` SubscriptionFilter[]
    - `key` string, required: What is the key to filter the data before sending to the webhook
    - `value` union, required: Must match `operator`: use a string or number for "eq" and "ne"; use a non-empty array only for "in".
      - string
      - number
      - string[]
    - `operator` 'eq' | 'ne' | 'in', required: What is the operator to filter the data
  - `subscription_actions` SubscriptionAction[]: Actions are used only for internal apps. (Not allowed to external apps)
    - `action_id` 'run_ai_prompt' | 'send_channel_message_reminder', required: What is the action to perform
    - `entity_type` 'ai_prompt' | 'channel_reminder': What is the entity_type to perform the action on (required when entity_id is provided)
    - `entity_id` string: What is the entity_id to perform the action on (required when entity_type is provided)
    - `metadata` ActionMetadata
      - `conversation_id` string: The conversation/channel ID where the reminder message should be sent
      - `send_as_bot` boolean: Whether the message should be sent as a bot. If true, bot_user_id should be provided
      - `message` string: The message text to send. Either message or from_message_id must be provided
      - `links` string[]: Array of links to be attached to the message
  - `webhook_headers` object, nullable: Custom HTTP headers Carbon Voice will forward on every webhook delivery for this subscription. Pass null to clear previously set headers; omit the field to leave existing headers unchanged.

## Response `201`

- SubscribedUser
  - `created_at` string, date-time, required: The date and time at which the resource was created.
  - `updated_at` string, date-time, required: The date and time at which the resource was last updated.
  - `id` string, required: The primary key of the resource.
  - `client_id` string, required
  - `user_id` string, required
  - `subscriptions` string[], required: Array of subscription events or triggers (including "schedule" for time-based triggers)
  - `webhookURL` string: Webhook URL to send the data
  - `subscription_filters` SubscriptionFilter[]
    - `key` string, required: What is the key to filter the data before sending to the webhook
    - `value` union, required: Must match `operator`: use a string or number for "eq" and "ne"; use a non-empty array only for "in".
      - string
      - number
      - string[]
    - `operator` 'eq' | 'ne' | 'in', required: What is the operator to filter the data
  - `subscription_actions` SubscriptionAction[]
    - `action_id` 'run_ai_prompt' | 'send_channel_message_reminder', required: What is the action to perform
    - `entity_type` 'ai_prompt' | 'channel_reminder': What is the entity_type to perform the action on (required when entity_id is provided)
    - `entity_id` string: What is the entity_id to perform the action on (required when entity_type is provided)
    - `metadata` ActionMetadata
      - `conversation_id` string: The conversation/channel ID where the reminder message should be sent
      - `send_as_bot` boolean: Whether the message should be sent as a bot. If true, bot_user_id should be provided
      - `message` string: The message text to send. Either message or from_message_id must be provided
      - `links` string[]: Array of links to be attached to the message
  - `webhook_headers` object: Custom HTTP headers forwarded on webhook deliveries for this subscription.

---

[API](https://skmtc.dev/carbonvoice/apis/carbon-voice-api.md) · [All operations](https://skmtc.dev/carbonvoice/apis/carbon-voice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/carbonvoice/apis/carbon-voice-api/revisions/b91c5c845122?raw)