Skip to main content

​
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:
FieldTypeDescription
from / tostringThe best available identifier (phone number preferred, LID as fallback)
fromType / toTypestringEither pn (phone number) or lid
phoneNumberstring | nullThe phone number when WhatsApp provides it
lidstring | nullThe LID when the contact uses this format
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.

​
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: 
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.
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

​
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.