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

# Webhooks

> Send real-time agent events to your own HTTP endpoints for custom integrations.

Webhooks let you receive real-time notifications when events happen in your Tiny Talk agent. Use webhooks to integrate with custom systems, CRMs, or any tool that accepts HTTP requests.

## Creating a webhook

1. Go to **Integrations → Webhooks** in your dashboard
2. Click **Create Webhook Endpoint**
3. Enter your **Webhook URL** (must be HTTPS)
4. Optionally add a **Description** to note what this endpoint is used for
5. Toggle on the events you want to listen to
6. Click **Create**

## Event types

| Event                  | Description                                                                    |
| ---------------------- | ------------------------------------------------------------------------------ |
| `contact.created`      | A new contact is created                                                       |
| `message.created`      | A new message is created (visitor, AI, or human agent)                         |
| `contact.lead.updated` | A contact with a lead role is updated (e.g., submitted the qualification form) |
| `conversation.created` | A new conversation is created                                                  |
| `takeover.request`     | A visitor requested to speak with a human agent                                |

## Managing webhooks

The webhook list shows all your endpoints with their URL, source, listening event, timestamps, and active status.

* **Active toggle** — Enable or disable a webhook without deleting it
* **Remove** — Permanently delete a webhook endpoint
* Click a webhook to edit its URL, description, or subscribed events

## Webhook secret and signature verification

Each webhook endpoint has a **Webhook Secret** (visible when editing the endpoint). Use this secret to verify that incoming requests are genuinely from Tiny Talk.

Tiny Talk signs the request body with the webhook secret and includes the signature in the `TinyTalk-Signature` header. To verify:

1. Compute an HMAC-SHA256 hash of the raw request body using your webhook secret
2. Compare it to the value in the `TinyTalk-Signature` header

<Info>
  Each request also includes an `Idempotency-Key` header that you can use to detect and handle duplicate deliveries.
</Info>

## Testing webhooks

Each event has a **Test** button (lightning icon) that sends a sample payload to your endpoint. Use this to verify your integration is working before going live.

For development, tools like [webhook.site](https://webhook.site) or [ngrok](https://ngrok.com) are useful for inspecting payloads without setting up a server.

## Payload format

Webhook payloads are sent as `POST` requests with a JSON body. The exact structure varies by event type — use the **Test** button to inspect sample payloads for each event.

## Retry behavior

If your endpoint returns a non-2xx response, Tiny Talk may retry the delivery. Ensure your endpoint:

* Responds with a `200` status code on success
* Handles duplicate events gracefully (use the `Idempotency-Key` header for deduplication)
* Responds within 30 seconds

<Info>
  Webhooks created by [Zapier](/integrations/zapier) and [Pabbly Connect](/integrations/pabbly) integrations also appear in the webhook list, marked with their source. Modifying or deleting these webhooks may break those integrations.
</Info>