Introduction to Webhooks

Concept

In this section, we cover the webhook responses used by the WhatsApp Web API.

Important

Your endpoint must accept POST requests to receive event notifications.

Remember: when creating the instance, you need to provide the URLs where you want to receive notifications.

What is it and what is it used for?

Webhooks are used to inform you about the sending and receiving of messages, as well as the current status of your instance.

The instance is the WhatsApp Web page we manage for your account.

If you are integrating your application with the WhatsApp Web API, you need to set up endpoints to receive notifications about all interactions that occur on the connected WhatsApp.

Our Webhooks

• Delivery: Notifies when a message is sent.
• Receive: Notifies whenever someone interacts with your number.
• Status: Allows you to check the status of a message: received, read, replied, or deleted.
• Disconnected: Indicates interruptions in communication between your device and WhatsApp.
• Connected: Indicates the start of communication between your device and WhatsApp.

Webhook Configuration

You can configure the webhook for your instance by accessing your account:

When creating a new instance, you can add configurations to receive messages.

Configuration via Dashboard

Access the admin panel, click on "Instances", view the desired instance, and edit the configurations.

Webhook on Send

Change Webhook URL via API

This API allows you to change the webhook URL for sending messages through a PUT request.

Base URL

Base URL: https://apiwhatsappweb.com/api/config/sent

Authentication

To authenticate the requests, you must include the API Key (apiKey) and the instance ID ID in the request header.

{
    "apiKey": "Your API key here",
    "id": "Your instance ID here"
}

How to Change the Webhook

Request Body

The request body should be a JSON object with the following structure:

{
    "URL": "https://Your_Website_here.com/api/config/sent" 
    // Send the URL where you want to receive notifications
}

Important

The WhatsApp Web API does not accept webhooks that are not HTTPS.

Webhook Responses

The send webhook allows you to be notified as soon as a message is successfully sent.

Response Example

{
    "message": "Text sent successfully!",
    "messageSent": "Message sent by you",
    "number": "Contact number",
    "messageId": "Message ID" // Allows you to check the message status later
}

{
    messageId: 'Message ID', // Allows you to access the message status later,
    message: 'Message sent by another person',  // Messages automatically expire in 30 days
    number: "Sent number",
    photo: 'Photo', // If it's not a photo, it will be null
    video: 'Video', // If it's not a video, it will be null,
    senderName: 'User name', // If not available, it will be 'Unknown'
    instanceName: 'Instance name registered on the platform',
    instanceId: "Instance ID registered on the platform",
    whatsappStatus: {
      message: "Received",
      description: 'Message sent by another person',
      title: 'Title' || null,
      url: 'URL sent by another person', // If not available, it will be null
      groupInvite: 'Group invitation' // If not available, it will be null
    }
};
    

{
    instanceName: "The name of the instance that disconnected", 
    instanceId: "The ID of the instance that disconnected",
    status: 'Disconnected',
    whatsappStatus: { message: "Disconnected" }
};
    

{
    instanceName: "The name of the instance that connected",
    instanceId: "The ID of the instance that connected",
    status: 'Connected',
    whatsappStatus: { message: "Connected" }
};