Webhook

Webhooks are user-defined HTTP callbacks that are triggered by specific events. Whenever a triggering event occurs, the WhatsApp Business API client sees the event, collects the data, and immediately sends a notification (HTTP request) to the WhatsApp URL specified in the application settings, updating the status of sent messages or indicating when you receive a message.

It is important that your Webhook returns an HTTPS 200 OK response to notifications. Otherwise, the WhatsApp Business API client will consider that notification a failure and will retry after a delay.

Webhook Configuration

To receive notifications, the customer needs to register the Webhook URL on the number. Set/update the Webhook URL:

PUT https://api.positus.global/v2/whatsapp/numbers/{chave}/webhook
Authorization: Bearer <seu-token>
Content-Type: application/json

{
  "webhook": "https://seu-dominio.com/webhook"
}

The webhook field is optional (it can be null to remove it) and has a maximum of 255 characters. If the Webhook URL is not set, notifications will not be delivered.

If your Webhook URL sits behind a firewall or allowlist, allow the Positus source IPs. See Webhook IP addresses.

In addition to the main Webhook, you can configure a secondary webhook (secondary_webhook). When set, it receives the same notifications as the main Webhook.

Test the Webhook (handshake): to validate that the URL is responding correctly, trigger a test message. Positus will send a test notification ("Beep Beep!") to the configured URL:

POST https://api.positus.global/v2/whatsapp/numbers/{chave}/positus-webhook
Authorization: Bearer <seu-token>

It is important that your Webhook returns an HTTP 200 OK response to notifications. Otherwise, the notification will be considered a failure and there will be retry attempts.

Set notification settings

Positus numbers use the WhatsApp Cloud API. On the registered Webhook URL, the customer receives a normalized subset of Meta’s payload (without the entry/changes envelope). The delivered objects are the raw Cloud API objects.

Name	object content
messages	Incoming message notifications
statuses	Message status updates
errors	Serious out-of-band errors

Whenever possible, names will be kept constant across functions. (For example, all date and time stamps are named timestamp.

New user identifiers (BSUID). With the arrival of WhatsApp usernames, webhook payloads now carry additional identification fields — user_id (BSUID), parent_user_id (parent BSUID) and profile.username. When a user adopts a username, the phone fields (wa_id, from, recipient_id) may be omitted from the payload. Handle this scenario by using user_id as the primary identifier. To understand these identifiers, see the BSUID and user identifiers page.

Notification Webhook format

An incoming message notification has the top-level { "contacts": [...], "messages": [...] }. A status notification has the top-level { "statuses": [...], "contacts": [...] } (contacts is only present when the status is not failed). Example (incoming text message)

{
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher",
        "username": "@kerryfisher"
      },
      "wa_id": "16315551234",
      "user_id": "BR.1234567890",
      "parent_user_id": "BR.ENT.1234567890"
    }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1518694235",
      "type": "text",
      "text": { "body": "Hello this is an answer" }
    }
  ]
}

The profile.username, user_id and parent_user_id fields only appear in the scenarios described on the BSUID page. The wa_id (and the message from) may be omitted when the user has adopted a username. The fields below are added to the contacts[] object (they do not replace the existing ones):

Field	Description
`contacts[].user_id`	User BSUID — identifier scoped to the business portfolio. Present in message webhooks.
`contacts[].parent_user_id`	Parent BSUID — only present if the portfolio is enrolled in a parent account.
`contacts[].profile.username`	Public username (`@name`) — only present if the user has adopted a username.
`contacts[].wa_id`	User’s phone number — may be omitted when a username is present (see 30-day rule).

The messages[].from field (sender’s phone number) follows the same behavior as wa_id: it may be absent when the user has adopted a username. Use the user_id present in the corresponding contacts[] object to identify the sender durably.

Message status updates

In addition to incoming messages, the customer receives status notifications for the messages they sent. These notifications have the top-level { "statuses": [...], "contacts": [...] }. Example (delivered status)

{
  "statuses": [
    {
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "status": "delivered",
      "timestamp": "1521497954",
      "recipient_id": "16315551234",
      "recipient_user_id": "BR.1234567890",
      "recipient_parent_user_id": "BR.ENT.1234567890"
    }
  ],
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher",
        "username": "@kerryfisher"
      },
      "wa_id": "16315551234",
      "user_id": "BR.1234567890",
      "parent_user_id": "BR.ENT.1234567890"
    }
  ]
}

The BSUID identification fields in the status object:

Field	Description
`statuses[].recipient_user_id`	Recipient’s BSUID. May be omitted if the message was sent to the phone number.
`statuses[].recipient_parent_user_id`	Recipient’s parent BSUID — only present if the portfolio is enrolled in a parent account.
`statuses[].recipient_id`	Recipient’s phone number — now optional; may be omitted when the user has adopted a username.

The contacts array that accompanies the status (when present) carries the same BSUID fields described in incoming messages: user_id, parent_user_id and profile.username. The status field can take the following values:

Value	Description
`sent`	The message was sent to the WhatsApp server.
`delivered`	The message was delivered to the recipient’s device.
`read`	The message was read by the recipient.
`failed`	The message failed to send.

When the status is failed, the status object includes an errors array with the failure details and contacts is not sent. Example (failed status)

{
  "statuses": [
    {
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "status": "failed",
      "timestamp": "1521497954",
      "recipient_id": "16315551234",
      "errors": [
        {
          "code": 131026,
          "title": "Message undeliverable"
        }
      ]
    }
  ]
}

Notification errors

When out-of-band errors occur during the normal operation of the application, the errors array will provide a description of the error. This type of error can be caused by temporary network connectivity errors, invalid credentials, management controllers with an unavailable status, and so on. If you receive an error, refer to Error and status messages for more information. Example

{
  "errors": [
    {
      "code": 131026,
      "title": "Message undeliverable",
      "details": "Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
      "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes"
    }
  ]
}

The errors object
The errors object contains the following parameters:

Field name	Description	Type
code	Error code	Numeric
title	Error title	String
details	Optional. Error details provided, if available/applicable	String
href	Optional. Details of the error location.	String

Incoming message notifications

You receive a notification when your business receives a message. The messages object section presents all the information that can be received about an incoming message.

Example: Incoming Text message

{
  "contacts": [ {
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  } ],
  "messages":[{
    "from": "16315551234",
    "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
    "timestamp": "1518694235",
    "text": {
      "body": "Hello this is an answer"
    },
    "type": "text"
  }]
} 

Example: Incoming static location message

{
  "contacts": [ {
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  } ],
 "messages":[{
   "from":"16315551234",
   "id":"wamid.HBgLMTYzMTU1NTEyMzQ...",
   "location":{
      "address":"Main Street Beach, Santa Cruz, CA",
      "latitude":38.9806263495,
      "longitude":-131.9428612257,
      "name":"Main Street Beach",
      "url":"https://foursquare.com/v/4d7031d35b5df7744"},
   "timestamp":"1521497875",
   "type":"location"
  }]
} 

Example: Incoming message with contacts

{
    "contacts": [ {
        "profile": {
          "name": "Kerry Fisher"
        },
        "wa_id": "16315551234"
    } ],
    "messages": [
        {
            "contacts": [
                {
                    "addresses": [
                        {
                            "city": "Menlo Park",
                            "country": "United States",
                            "country_code": "us",
                            "state": "CA",
                            "street": "1 Hacker Way",
                            "type": "WORK",
                            "zip": "94025"
                        }
                    ],
                    "birthday": "2012-08-18",
                    "contact_image": "/9j/4AAQSkZJRgABAQEAZABkAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCABgAGADASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD1NLloxyc0j3bNUHDGgoCMVNkBbhutvVqc9yGHNZ3kOW4Wn/ZnQZzSsgLLXAA61Xn1O2t4zLcyJHGvV3OAKMADmvOviLq9m11a2bO/l2xLzoqnliF2j9f1NTLRXHGHM7Hb2vivSL+8e0s7yKaVeyHg/Q9D+FXWuHPOzivFodT0WZkeF44bheVdE2EH+Rr2+zuVuNPt7gqh86JX+TkcjPFTCdy6lNQ2dyr5+G5WpRe4HTFWWSOQfwioZbCIn5XNaXRmQPegjmqrKLh+...",
                    "emails": [
                        {
                            "email": "kfish@fb.com",
                            "type": "WORK"
                        }
                    ],
                    "ims": [
                        {
                            "service": "AIM",
                            "user_id": "kfish"
                        }
                    ],
                    "name": {
                        "first_name": "Kerry",
                        "formatted_name": "Kerry Fisher",
                        "last_name": "Fisher"
                    },
                    "org": {
                        "company": "Facebook"
                    },
                    "phones": [
                        {
                            "phone": "+1 (940) 555-1234",
                            "type": "CELL"
                        },
                        {
                            "phone": "+1 (650) 555-1234",
                            "type": "WORK",
                            "wa_id": "16505551234"
                        }
                    ],
                    "urls": [
                        {
                            "url": "https://www.facebook.com",
                            "type": "WORK"
                        }
                    ]
                }
            ],
            "from": "16505551234",
            "id": "wamid.HBgLMTY1MDU1NTEyMzQ...",
            "timestamp": "1537248012",
            "type": "contacts"
        }
    ]
}

System message: user changed identifier (`user_changed_user_id`)

When a user’s identifier changes (for example, when switching phone numbers), WhatsApp sends a system message of type system with system.type equal to user_changed_user_id. It arrives inside the messages array, in the same format as other incoming messages. Use it to update the contact’s link to the new user_id.

{
  "contacts": [
    {
      "profile": { "name": "Kerry Fisher" },
      "user_id": "BR.9876543210"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1521827831",
      "type": "system",
      "system": {
        "type": "user_changed_user_id",
        "customer": "BR.1234567890",
        "user_id": "BR.9876543210",
        "parent_user_id": "BR.ENT.9876543210",
        "body": "The user changed identifier"
      }
    }
  ]
}

Field	Description
`system.type`	`user_changed_user_id` — identifies the trigger.
`system.customer`	User’s previous BSUID — use it to locate the existing contact.
`system.user_id`	User’s new BSUID.
`system.parent_user_id`	New parent BSUID — present if the portfolio is enrolled in a parent account.
`system.body`	Descriptive text of the system message.

Incoming media message notifications

When a message with media is received, the notification sent to your Webhook contains a media object with the fields that identify the file. In the Cloud API, the media object only carries id, mime_type, and sha256 (plus an optional caption for image, document, and video). There are no file or link fields. To download the media, use the id in the download endpoint: GET https://api.positus.global/v2/whatsapp/numbers/{chave}/media/{id}.

Example: Incoming message with image

{
  "contacts": [
    { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1521497954",
      "type": "image",
      "image": {
        "id": "1234567890",
        "mime_type": "image/jpeg",
        "sha256": "29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db",
        "caption": "Check out my new phone!"
      }
    }
  ]
}

Example: Incoming message with document

{
  "contacts": [
    { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1522189546",
      "type": "document",
      "document": {
        "id": "1234567890",
        "mime_type": "application/pdf",
        "sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e",
        "caption": "80skaraokesonglistartist"
      }
    }
  ]
}

Example: Incoming message with audio

In the Cloud API, audio messages (including voice messages) are delivered with the type audio, not voice.

{
  "contacts": [
    { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1521827831",
      "type": "audio",
      "audio": {
        "id": "1234567890",
        "mime_type": "audio/ogg; codecs=opus",
        "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
      }
    }
  ]
}

Example: Incoming message with video

{
  "contacts": [
    { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1521827831",
      "type": "video",
      "video": {
        "id": "1234567890",
        "mime_type": "video/mp4",
        "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710",
        "caption": "Look at this!"
      }
    }
  ]
}

Example: Incoming message with sticker

{
  "contacts": [
    { "profile": { "name": "Kerry Fisher" }, "wa_id": "16315551234" }
  ],
  "messages": [
    {
      "from": "16315551234",
      "id": "wamid.HBgLMTYzMTU1NTEyMzQ...",
      "timestamp": "1521827831",
      "type": "sticker",
      "sticker": {
        "id": "1234567890",
        "mime_type": "image/webp",
        "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
      }
    }
  ]
}

Incoming replies to sent messages

Users can reply to a specific message on WhatsApp. So that the business understands the context of the reply to a message, we include the context object. This context object provides the id of the message the customer replied to and the WhatsApp ID of the sender of the original message.

Example: Customer replied to your message

{
  "contacts": [ {
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  } ],
   "messages":[{
      "context":{
         "from":"16315558011",
         "id":"wamid.HBgLMTYzMTU1NTgwMTE..."
         },
      "from":"16315551234",
      "id":"wamid.HBgLMTYzMTU1NTEyMzQ...",
      "text":{"body":"Yes, count me in!"},
      "timestamp":"1521499915",
      "type":"text"
  }]
}

Workspace event webhooks (BSUID)

In addition to message and status notifications (delivered in the raw Cloud API format), Positus sends two workspace events related to BSUID. These events use a different envelope: a top-level object with the event field (event name), the workspace object (workspace identification) and an object with the event data — named contact or number, depending on the case.

BSUID update (`user_id_update`)

Triggered when a user’s BSUID (or parent BSUID) is updated. It carries the previous and current values of each identifier. The data comes in the contact object.

{
  "event": "user_id_update",
  "workspace": {
    "id": "9f8b7c6d-...",
    "provider": { "id": 1, "name": "Positus V2" },
    "type_workspace": "...",
    "name": "My Company",
    "business_id": "1234567890",
    "waba_id": "9876543210"
  },
  "contact": {
    "wa_id": "16315551234",
    "previous_user_id": "BR.1234567890",
    "current_user_id": "BR.9876543210",
    "previous_parent_user_id": "BR.ENT.1234567890",
    "current_parent_user_id": "BR.ENT.9876543210",
    "timestamp": "1521827831",
    "detail": "...",
    "waba_id": "9876543210",
    "phone_number_id": "16315551234"
  }
}

Field	Description
`contact.wa_id`	User’s phone number associated with the event (may be omitted).
`contact.previous_user_id`	User’s previous BSUID.
`contact.current_user_id`	User’s current BSUID.
`contact.previous_parent_user_id`	Previous parent BSUID (if applicable).
`contact.current_parent_user_id`	Current parent BSUID (if applicable).
`contact.timestamp`	Time of the update.
`contact.detail`	Additional event detail, when provided by Meta.
`contact.waba_id`	WhatsApp Business Account (WABA) ID.
`contact.phone_number_id`	Phone number ID of the line.

Line username update (`business_username_update`)

Triggered when the status of your official line’s username changes (the public @name of the business number). The data comes in the number object.

{
  "event": "business_username_update",
  "workspace": {
    "id": "9f8b7c6d-...",
    "provider": { "id": 1, "name": "Positus V2" },
    "type_workspace": "...",
    "name": "My Company",
    "business_id": "1234567890",
    "waba_id": "9876543210"
  },
  "number": {
    "display_phone_number": "16315551234",
    "username": "@mycompany",
    "status": "approved",
    "timestamp": "1521827831",
    "waba_id": "9876543210"
  }
}

Field	Description
`number.display_phone_number`	Phone number of the official line whose username changed.
`number.username`	Line username (`@name`).
`number.status`	Username status: `approved`, `deleted` or `reserved`.
`number.timestamp`	Time of the update.
`number.waba_id`	WhatsApp Business Account (WABA) ID.

Official WhatsApp Cloud API documentation

Positus uses the WhatsApp Cloud API and delivers the objects in the same format as Meta’s official standard. The complete and up-to-date documentation can be found at the link below:https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components

​Webhook

​Webhook Configuration

​Set notification settings

​Notification Webhook format

​Message status updates

​Notification errors

​Incoming message notifications

​Example: Incoming Text message

​Example: Incoming static location message

​Example: Incoming message with contacts

​System message: user changed identifier (user_changed_user_id)

​Incoming media message notifications

​Example: Incoming message with image

​Example: Incoming message with document

​Example: Incoming message with audio

​Example: Incoming message with video

​Example: Incoming message with sticker

​Incoming replies to sent messages

​Example: Customer replied to your message

​Workspace event webhooks (BSUID)

​BSUID update (user_id_update)

​Line username update (business_username_update)

​Official WhatsApp Cloud API documentation

Webhook

Webhook Configuration

Set notification settings

Notification Webhook format

Message status updates

Notification errors

Incoming message notifications

Example: Incoming Text message

Example: Incoming static location message

Example: Incoming message with contacts

System message: user changed identifier (`user_changed_user_id`)

Incoming media message notifications

Example: Incoming message with image

Example: Incoming message with document

Example: Incoming message with audio

Example: Incoming message with video

Example: Incoming message with sticker

Incoming replies to sent messages

Example: Customer replied to your message

Workspace event webhooks (BSUID)

BSUID update (`user_id_update`)

Line username update (`business_username_update`)

Official WhatsApp Cloud API documentation