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

# Introduction

> Use webhooks to notify your application about WhatsApp events

## Understanding LIDs (Linked IDs)

WhatsApp has introduced LIDs (Linked IDs) as privacy-focused identifiers that replace phone numbers in many contexts. Unlike phone numbers, LIDs are pseudonymous identifiers that remain consistent for a contact but don't reveal their actual phone number.

### What this means for webhooks

Our webhook events include both identifiers when available:

| Field                 | Type           | Description                                                             |
| --------------------- | -------------- | ----------------------------------------------------------------------- |
| `from` / `to`         | string         | The best available identifier (phone number preferred, LID as fallback) |
| `fromType` / `toType` | string         | Either `pn` (phone number) or `lid`                                     |
| `phoneNumber`         | string \| null | The phone number when WhatsApp provides it                              |
| `lid`                 | string \| null | The LID when the contact uses this format                               |

<Info>
  When you receive both `lid` and `phoneNumber` together, we recommend storing this mapping for future reference. This allows you to match contacts in external systems where only a phone number is available, even when only the LID is provided in the received event.
</Info>

## What is a webhook?

We use webhooks to push real-time notifications to you about your WhatsApp devices. All webhooks use HTTPS and deliver a JSON payload that can be used by your application. You can use webhook feeds to do things like:

* Process incoming messages and send automated responses
* Track when a device connects or disconnects
* Monitor QR code generation for device pairing
* Build real-time integrations with your existing systems

In case webhooks are not successfully received by your endpoint, we automatically retry to send the request with a progressive backoff period of 30 seconds, 1 minute, 5 minutes and 1 hour.

## Steps to receive a webhook

You can start receiving real-time events in your app using the steps below:

* Create a local endpoint to receive requests
* Register your development webhook endpoint in the Chatlevel app
* Test that your webhook endpoint is working
* Deploy your webhook endpoint to production

### 1. Create a local endpoint to receive requests

In your local application, create a new route that can accept POST requests.

For example, you can add an API route on Next.js:

```typescript theme={null}
import type { NextApiRequest, NextApiResponse } from 'next';

export default (req: NextApiRequest, res: NextApiResponse) => {
  if (req.method === 'POST') {
    const payload = req.body;
    console.log(payload);
    res.status(200);
  }
};
```

On receiving an event, you should respond with an HTTP 200 OK to signal that the event was successfully delivered.

### 2. Register your development webhook endpoint

Register your publicly accessible HTTPS URL in the Chatlevel app.

<Tip>
  You can create a tunnel to your localhost server using a tool like ngrok. For example: [https://8733-191-204-177-89.sa.ngrok.io/api/webhooks](https://8733-191-204-177-89.sa.ngrok.io/api/webhooks)
</Tip>

### 3. Test that your webhook endpoint is working properly

Create a few test trigger events for your connected device to check that your webhook endpoint is receiving events correctly.

### 4. Deploy your webhook endpoint

After you're done testing, deploy your webhook endpoint to production.

### 5. Register your production webhook endpoint

Once your webhook endpoint is deployed to production, you can register it in the live dashboard.