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

# Webhooks

> PingBack receives webhook events from connected channels to route inbound messages into conversations.

PingBack exposes webhook endpoints that your connected channel providers call to deliver inbound messages. When a customer sends a message on WhatsApp, Instagram, Telegram, X, or email, the provider posts the event to the corresponding PingBack endpoint, and PingBack routes it into the right conversation automatically.

These are **inbound** webhooks — the channel platforms call PingBack, not the other way around.

<Note>
  You configure these webhook URLs in your channel provider's dashboard. Once you connect a channel in PingBack, the routing and processing happen automatically — you do not need to write any additional code.
</Note>

## Available webhook endpoints

| Channel     | Method | Endpoint                                 | Notes                                                 |
| ----------- | ------ | ---------------------------------------- | ----------------------------------------------------- |
| WhatsApp    | GET    | `/api/v1/webhooks/whatsapp`              | Meta verification challenge.                          |
| WhatsApp    | POST   | `/api/v1/webhooks/whatsapp`              | Inbound message delivery.                             |
| Instagram   | GET    | `/api/v1/webhooks/instagram`             | Meta verification challenge.                          |
| Instagram   | POST   | `/api/v1/webhooks/instagram`             | Inbound message delivery.                             |
| Email       | POST   | `/api/v1/webhooks/email`                 | Inbound email delivery.                               |
| Telegram    | POST   | `/api/v1/webhooks/telegram/{channel_id}` | Replace `{channel_id}` with your Telegram channel ID. |
| X (Twitter) | POST   | `/api/v1/webhooks/x/{channel_id}`        | Replace `{channel_id}` with your X channel ID.        |

## Meta webhook verification (WhatsApp and Instagram)

When you register a webhook URL in the Meta App Dashboard, Meta sends a one-time `GET` request to verify that your endpoint is reachable. PingBack handles this automatically.

Meta sends three query parameters:

| Parameter          | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| `hub.mode`         | Always `"subscribe"` for a verification request.            |
| `hub.verify_token` | The token you entered when registering the webhook in Meta. |
| `hub.challenge`    | A random string Meta expects you to echo back.              |

PingBack responds with the `hub.challenge` value when `hub.verify_token` matches `pingback_verify`. Use `pingback_verify` as your verify token when setting up the webhook in your Meta App.

<Steps>
  <Step title="Open your Meta App Dashboard">
    Go to [developers.facebook.com](https://developers.facebook.com), select your app, and navigate to **WhatsApp → Configuration** (or **Instagram → Webhooks**).
  </Step>

  <Step title="Enter the webhook URL">
    Set the callback URL to:

    ```
    https://api.pingback.live/api/v1/webhooks/whatsapp
    ```

    For Instagram, use:

    ```
    https://api.pingback.live/api/v1/webhooks/instagram
    ```
  </Step>

  <Step title="Enter the verify token">
    Set **Verify Token** to:

    ```
    pingback_verify
    ```
  </Step>

  <Step title="Subscribe to message events">
    Select the `messages` field under **Webhook Fields** and click **Verify and Save**. Meta will call PingBack's GET endpoint to confirm the token, then begin delivering events via POST.
  </Step>
</Steps>

## Telegram and X setup

For Telegram and X, the webhook URL includes your channel ID. You can find your channel ID in PingBack under **Settings → Channels** after connecting the channel.

**Telegram example:**

```
https://api.pingback.live/api/v1/webhooks/telegram/123
```

**X example:**

```
https://api.pingback.live/api/v1/webhooks/x/456
```

Register these URLs in your Telegram bot settings or X Developer Portal respectively. PingBack handles message parsing and routing once the webhook is active.

## What happens after a webhook fires

When PingBack receives a webhook event, it:

1. Identifies the channel and the customer who sent the message.
2. Finds or creates a conversation for that customer.
3. Saves the message and emits a `new_message` Socket.IO event to your connected agents in real time.

Your agents see the message appear immediately in the inbox without any additional setup.

For more on connecting individual channels, see the [Channels](/channels/web-widget) section.