> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tied.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event catalogue

> The server accepts 12 event names. The published schema lists 8.

You subscribe by passing an array of event names to `subscriptions` when you create or update a webhook:

```bash theme={null}
curl -X POST https://app.tied.com/api/v1/accounts/1/webhooks \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhook": {"url": "https://example.com/hook", "subscriptions": ["conversation_created", "message_created"]}}'
```

Any name outside the real allowlist is rejected with a 422 (`Invalid events`) — see [Errors](/api-reference/errors).

<Warning>
  **The published OpenAPI schema's `subscriptions` enum lists 8 events. The server actually accepts 12.** `inbox_created`, `inbox_updated`, `conversation_typing_on`, and `conversation_typing_off` are real, whitelisted, subscribable events — they're just missing from the generated reference's enum. `conversation_typing_on`/`off` at least show up as checkboxes in the dashboard's own webhook form; `inbox_created` and `inbox_updated` don't appear there either, so the only way to know they exist is to send them and see them accepted. The table below is the real list, taken from the model validation that actually enforces it.
</Warning>

## The 12 events

| Event | Fires when |
| - | - |
| `conversation_created` | A new conversation is created. |
| `conversation_updated` | A conversation's attributes change. |
| `conversation_status_changed` | A conversation's `status` specifically changes — open, resolved, pending, or snoozed, in either direction. |
| `contact_created` | A new contact is created. |
| `contact_updated` | A contact's attributes change. Doesn't fire if the update touched nothing that actually changed. |
| `message_created` | A new message is created — see the gate below. |
| `message_updated` | An existing message is updated — same gate. |
| `webwidget_triggered` | The web widget's contact\_inbox reports a triggered event. |
| `inbox_created` | A new inbox is created. |
| `inbox_updated` | An inbox's attributes change. Same "only if something actually changed" gate as contacts. |
| `conversation_typing_on` | An agent or contact starts typing in a conversation. |
| `conversation_typing_off` | Typing stops. |

<Note>
  `conversation_status_changed` is the only status-related event you can subscribe to. The app has finer-grained internal events for "opened" and "resolved" specifically, used for other internal notifications — they aren't on the webhook allowlist, so don't try to subscribe to them by name.
</Note>

## The message gate: not every message fires an event

`message_created` and `message_updated` only fire for messages that are `incoming`, `outgoing`, or a `template`. **Activity messages (join/leave notices, assignment changes) and private notes never trigger a webhook.** If you're trying to build an integration off internal agent notes, this event stream isn't where that data comes from — you'd need to poll the messages endpoint and filter differently.

## Subscriptions aren't scoped by inbox, even if you set `inbox_id`

The webhook create/update payload accepts an `inbox_id`, and it's stored. It doesn't do anything to delivery. Every account-level webhook receives every event that matches its `subscriptions`, from every inbox in the account, regardless of what `inbox_id` you set on the webhook itself. If you need per-inbox filtering, do it in your own handler by reading `inbox_id` off the payload — see [Payload schemas](/api-reference/webhooks/payloads).

<Info>
  There's a separate mechanism for a single inbox's own webhook URL — the `webhook_url` configured directly on an API-channel inbox — but it isn't managed through this endpoint and isn't what `inbox_id` on a `Webhook` record controls.
</Info>

## Next

<CardGroup cols={2}>
  <Card title="Payload schemas" icon="braces" href="/api-reference/webhooks/payloads">
    What's actually in the body for each of these.
  </Card>

  <Card title="Signature verification" icon="shield-check" href="/api-reference/webhooks/signatures">
    What Tied does — and doesn't — do to prove a payload is genuine.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.