In this article, we tell you how to connect webhooks, in what form we send them, and what we expect in response.

How we send webhooks and what we expect in return

We send webhooks using the POST method to the specified URI. It may include a query "string".

If we have your crmKey, we add the Authorization: Bearer ${crmKey} header. If not, we don't add the Authorization header at all.

Webhooks contain JSON in the body and the corresponding header Content-Type: application/json; charset-utf-8. An object is encoded in JSON with properties that correspond to webhook types.

One webhook can contain messages and statuses types at the same time. The webhooks of the createContact and createDeal types always contain only one type.

In response, we expect the code 200 OK. In some cases, we wait for certain information in the body of the response. Timeout — 30 s.

How to enable webhooks

To subscribe to webhooks, you must invoke:

{
  "webhooksUri": "string",
  "subscriptions": {
    "messagesAndStatuses": boolean,
    "contactsAndDealsCreation": boolean,
    "channelsUpdates": boolean,
    "templateStatus": boolean
  }
}

The body must contain JSON with parameters:

subscriptions (object)

When connecting to the specified url, a POST test request {test: true } will be sent, in reply to which the server should return 200 if webhooks are successfully connected, otherwise a :"Webhooks request not valid. Response status must be 200″.

Request example

 curl --location --request PATCH 'https://api.wazzup24.com/v3/webhooks' \
--header 'Authorization: Bearer w11cf3444405648267f900520d454368d27' \
--header 'Content-Type: application/json' \
--data-raw '{
"webhooksUri": "https://example.com/webhooks",
"subscriptions": {
"messagesAndStatuses": true,
"contactsAndDealsCreation": true
}
}'

Response example

 {
ok
}

Errors

In addition to common errors for all routes, there can be:

Checking the address for receiving webhooks

To check the currently set callback URL, call

Response example

 HTTP/1.1 200 OK
``json
{
"webhooksUri": "https://example.com/webhooks",
{ "subscriptions": {
{ "messagesAndStatuses": { "true",
{ "contactsAndDealsCreation": "true"
}
}
``

Webhook for new messages, editing and deleting messages

The webhook will send a JSON object with the messages key, the value of which is an array of objects with the following parameters:

{
  "messages": [
    {
      "messageId": "string",
      "channelId": "string",
      "chatType": "string",
      "chatId": "string",
      "dateTime": "string",
      "type": "string",
      "status": "string",
      "error": {
        "error": "string",
        "description": "string"
      },
      "text": "string",
      "contentUri": "string",
      "authorName": "string",
      "authorId": "string",
      "isEcho": boolean,
      "instPost": { ... },
      "contact": {
        "name": "string",
        "avatarUri": "string",
        "username": "string",
        "phone": "string"
      },
      "interactive": [ ... ],
      "quotedMessage": { ... },
      "sentFromApp": boolean,
      "isEdited": boolean,
      "isDeleted": boolean,
      "oldInfo": {
        "oldText": "string",
        "oldAuthorId": "string",
        "oldAuthorName": "string"
      }
    }
  ]
}

error (object)

instPost (object)

contact (object)

oldInfo (object)

 {
id: '2430659146657243411_41370968890',
src: 'https://www.instagram.com/p/CG7b52ejyET',
sha1: 'dc8c036b4a0122bb238fc38dcb0391c125e916f2',
likes: 0,
author: 'wztestdlv',
comments: 22,
timestamp: 1603977171000,
updatedAt: 1608905897958,
authorName: '',
authorId: '798633247',
description: 'Beauty',
previewSha1: '3a55c2920912de4b6a66d24568470dd4ad367c34',
imageSrc: 'https://store.dev-wazzup24.com/dc8c036b4a0122bb238fc38dcb0391c125e916f2',
previewSrc: 'https://store.dev-wazzup24.com/3a55c2920912de4b6a66d24568470dd4ad367c34'
}

 {
  "messages": [
    {
      "messageId": "6a2087e8-e0f4-9999-b968-9d9999933c81",
      "dateTime": "2025-05-06T14:16:00.002Z",
      "channelId": "b96a353b-9999-4cac-8413-ba99999f981",
      "chatType": "whatsapp",
      "chatId": "79999999999",
      "type": "image",
      "isEcho": false,
      "contact": {
        "name": "79999999999",
        "avatarUri": "https://store.wazzup24.com/0e999997ae07d2083c687253b8baed9999a26fa";
      },
      "contentUri": "https://store.wazzup24.com/e51159999e0046d628b3924161d411e5812d2546/?filename=f9ebe1b1-3ed5-4ec2-97fb-03f0c25e413f.was";,
      "status": "inbound"
    }
  ]
}
    

 {
  "messages": [
    {
      "messageId": "caa9999-cce3-424c-86cd-05f99995073",
      "dateTime": "2025-05-06T14:18:00.001Z",
      "channelId": "b96a999e-06f5-4cac-8413-ba999993f981",
      "chatType": "whatsapp",
      "chatId": "79999999999",
      "type": "text",
      "isEcho": false,
      "contact": {
        "name": "79999999999",
        "avatarUri": "https://store.wazzup24.com/0e82ead97ae07d9999c687253b8baed2365a26fa";
      },
      "text": "Тестовый\n• Вариант1\n• Вариант2",
      "status": "inbound"
    }
  ]
}
    

Webhook about updating the status of outgoing messages

The webhook will send a JSON object with the statuses key, the value of which will contain an array of objects with the following parameters:

{
  "statuses": [
    {
      "messageId": "string",
      "timestamp": "string",
      "status": "string",
      "error": {
        "error": "string",
        "description": "string",
        "data": "string"
      }
    }
  ]
}

error (object)

{
"statuses": [
{
"messageId": "be3dc577-60c4-4fc8-83a5-8c358e0bfe15", // guid of the message whose status update we are notifying
"timestamp": "2025-02-05T06:01:07.499Z", // is the time of receiving status update information
"status": "delivered"
}
]
}

Webhooks about creating a new contact, deal

Send when you need to create a contact or transaction in CRM. This happens in 3 cases:

Case 1: in item 3 of the integration settings "Every new client is assigned to the first respondent" is selected.

A new client writes. An employee replies to them. Wazzup sends a webhook about new contact and deal creation if funnels with stages are loaded from CRM.

Case 2: "Sales reps are assigned new clients in turn" is selected in item 3 of the integration settings.

A new client writes. Wazzup sends a webhook about creating a new contact and deal if funnels with stages are loaded from CRM.

Case 3: When clicking the "+" button in the "Deals" list to create a new deal inside the Wazzup chats:

We first check if the contact already exists in our database.

If the contact already exists, we send a webhook to initiate deal creation:

 { 
createDeal: { 
responsibleUserId: '1', // the id of the user who was selected in turn or was the first to respond 
contacts: ['1'] // link of the deal with a newly created contact 
source: 'auto'|'byUser', // auto - on incoming or outgoing message, byUser - by the button in the "Deals" dropdown 
}, 
}

If the contact does not exist, we first send a webhook to initiate contact creation:

 {
createContact: {
responsibleUserId: '1', // id of the user who was selected in turn or was the first to respond
name: 'contacts.name', // contact name from the contacts table
contactData: [{ chatType, chatId }],
source: 'auto'|'byUser', // auto - on incoming or outgoing message, byUser - by button
},
}

After that, the CRM should create the contact and respond with 200 OK along with a JSON object of the new entity, matching the CRUD route signature for contacts.

Then, we will send a webhook to initiate deal creation.

Subsequently, the CRM should create the deal and similarly respond with 200 OK and a JSON object of the new entity, matching the CRUD route signature for deals.

Webhook about channel status change and changes in WABA account tier

Sent when the channel status changes.

{
  "channelsUpdates": [
    {
      "channelId": "string",
      "state": "string",
      "tier": "string",
      "qr": "string",
      "timestamp": number
    }
  ]
}

Example

{
    "channelsUpdates": [
        {
            "channelId": "d9e5721c-ce2b-444f-9627-60a8129d7e1f",
            "state": "qr",
            "timestamp": 1603977171000,
            "qr": "data:image/png;base64,iVBORw0KGgoAAAANS"
        }
    ]
}

Channel status values (state)

Webhook about new moderation status of a WABA template

{
  "templateGuid": "string",
  "name": "string",
  "status": "string"
}

Status values