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

# Webhooks

> Send real-time event notifications from Clarky to external systems

<Info>
  **Plan availability:** Pro or higher. See [Plans & Billing](/features/settings/plans).
</Info>

## What Are Webhooks?

Webhooks let Clarky push real-time notifications to your own systems whenever something interesting happens — a new conversation starts, a contact is created, a booking is confirmed, or sentiment turns negative. Instead of polling for updates, your services receive an HTTP request the moment an event occurs.

Common use cases:

* Notify a Slack channel when a user asks to speak with a human
* Sync new contacts into your data warehouse
* Trigger an automation in Zapier, Make, or n8n
* Update a custom CRM when a booking is confirmed
* Alert on-call staff when a conversation is flagged with negative sentiment

## Adding a Webhook

<Steps>
  <Step title="Open Webhooks settings">
    Go to **Settings > Webhooks** and click **Add Webhook**.
  </Step>

  <Step title="Name and describe it">
    Give the webhook a clear name (for example, "Notify Slack on Escalation") and an optional description so teammates know what it does.
  </Step>

  <Step title="Enter the destination URL">
    Paste the URL of the endpoint that should receive the event. This is usually provided by the service you're integrating with — a Slack incoming webhook, a Zapier catch hook, or your own server endpoint.
  </Step>

  <Step title="Choose an HTTP method">
    Most destinations expect **POST**, which is the default. **PUT**, **PATCH**, **GET**, and **DELETE** are also supported for special cases.
  </Step>

  <Step title="Select the events to trigger it">
    Pick one or more events from the list (see [Available Events](#available-events) below). The webhook will only fire when one of these events occurs.
  </Step>

  <Step title="Scope to specific agents (optional)">
    By default, a webhook applies to **all agents** in the workspace. You can narrow it to one or more specific agents if you only want notifications for a subset.
  </Step>

  <Step title="Save">
    Click **Create Webhook**. New webhooks are enabled by default and will start firing immediately.
  </Step>
</Steps>

## Available Events

Clarky can send a webhook for any of the following events:

<AccordionGroup>
  <Accordion title="Contact events">
    * **Contact Created** — When a new contact is created
    * **Contact Updated** — When a contact is updated
    * **Contact Deleted** — When a contact is deleted
  </Accordion>

  <Accordion title="Conversation events">
    * **Conversation Started** — When a new conversation starts
    * **Conversation Updated** — When a conversation is updated
    * **Conversation Bad Sentiment** — When a conversation is flagged with negative sentiment
    * **Escalation Requested** — When a user asks to speak with a human
  </Accordion>

  <Accordion title="Message events">
    * **Message Sent (Outbound)** — When the agent sends a message
    * **Message Received (Inbound)** — When a user sends a message
  </Accordion>

  <Accordion title="Booking events">
    * **Booking Created** — When a new booking is made
    * **Booking Confirmed** — When a booking is confirmed
    * **Booking Cancelled** — When a booking is cancelled
    * **Booking Rescheduled** — When a booking is rescheduled
    * **Booking Completed** — When a booking is marked as completed
    * **Booking No Show** — When an attendee doesn't show up
    * **Booking Reminder Sent** — When a booking reminder is sent
  </Accordion>
</AccordionGroup>

## Authentication

If your destination requires authentication, add a **Bearer Token** when creating or editing the webhook. Clarky will include it as an `Authorization` header on every request to that endpoint.

<Tip>
  The token is masked in the UI by default. Use the eye icon next to the field to reveal or hide it while editing.
</Tip>

<Warning>
  Treat bearer tokens like passwords. Anyone with the token can post to your endpoint as Clarky. If a token is exposed, rotate it on the receiving service and update the webhook.
</Warning>

## Customizing the Payload

By default, Clarky sends a structured JSON payload that includes the event name, a timestamp, and details about the conversation, contact, and agent. You can override this with your own template if the receiving service expects a specific shape (for example, Slack's `text` field).

The payload editor supports inserting variables that are replaced at delivery time. Click any variable to drop it at your cursor:

| Variable               | Description                                      |
| ---------------------- | ------------------------------------------------ |
| `{{event}}`            | Event name (for example, `conversation.started`) |
| `{{timestamp}}`        | ISO 8601 timestamp of the event                  |
| `{{botId}}`            | The agent's unique ID                            |
| `{{botName}}`          | The agent's display name                         |
| `{{conversationId}}`   | Unique conversation ID                           |
| `{{conversationUrl}}`  | Direct link to the conversation in your inbox    |
| `{{firstMessage}}`     | The user's first message                         |
| `{{type}}`             | Conversation type — chat, text, voice, or email  |
| `{{phoneNumber}}`      | Phone number (for voice and text conversations)  |
| `{{firstName}}`        | Contact's first name                             |
| `{{lastName}}`         | Contact's last name                              |
| `{{email}}`            | Contact's email                                  |
| `{{sentimentScore}}`   | Sentiment score from 0 to 100                    |
| `{{sentimentSummary}}` | Short summary of the conversation sentiment      |

Clarky validates your template as you type and won't let you save invalid JSON.

<Tip>
  Leave the payload template empty to use the default payload, which includes all standard fields. Only customize it when the receiving service expects a specific format.
</Tip>

## Enabling and Disabling Webhooks

Each webhook has a toggle switch on its card. Turn a webhook off temporarily — for example, while you're debugging a downstream system — without deleting it. Disabled webhooks don't fire and don't count toward delivery activity.

## Testing a Webhook

The simplest way to verify a webhook is to trigger one of its events in a sandbox conversation:

<Steps>
  <Step title="Pick a low-impact event">
    For example, **Conversation Started** or **Message Received (Inbound)**.
  </Step>

  <Step title="Open your widget or send a message">
    Start a test conversation with the agent the webhook is scoped to.
  </Step>

  <Step title="Check the receiving system">
    Confirm the request arrived in Slack, Zapier, your server logs, or wherever the URL points.
  </Step>
</Steps>

For destinations like Webhook.site or RequestBin, you can paste a temporary inspection URL into the **URL** field while you build out your real integration.

## Managing Existing Webhooks

From the Webhooks list you can:

* **Toggle** a webhook on or off without deleting it
* **Edit** the URL, events, agent scope, or payload template
* **Delete** a webhook you no longer need

Deleting a webhook is permanent — once removed, no further events will be sent to that endpoint.

<Card title="Back to Settings" icon="gear" href="/features/settings/overview">
  Return to Settings overview
</Card>