Message Status Webhook
Instructions for building a webhook to receive message status updates.
🌐 Webhook URL
You need to provide us with your Webhook URL to receive message status notifications.
Example URL:
https://your-domain.com/webhook
📦 Data Structure Sent to the Webhook
- Method:
GET - Timeout: 2 seconds
The parameter structure sent depends on how the message was sent: single send (sending individual messages) or batch send (sending in bulk).
1️⃣ Case: Single Send
| Parameter | Meaning | Data Type |
|---|---|---|
msg_id | msg_id returned when sending the message via API | String |
status | Message status (success, failed) | String |
error_code | Error code (if any) | String / Null |
CURL Example:
curl -X GET "https://your-domain.com/webhook?msg_id=8a4938af-eef9-462f-b9aa-06b7520039c9&status=success&error_code=null"
Example data (JSON format, for reference on structure):
{
"msg_id": "8a4938af-eef9-462f-b9aa-06b7520039c9",
"status": "success",
"error_code": null,
}
2️⃣ Case: Batch Send
| Parameter | Meaning | Data Type |
|---|---|---|
msg_id | msg_id returned when sending the message via API | String |
status | Message status (success, failed) | String |
error_code | Error code (if any) | String / Null |
phone | Recipient phone number (format 84x) | String |
tracking_id | Tracking ID included with each item in the data array when calling the batch send API | String |
CURL Example:
curl -X GET "https://your-domain.com/webhook?msg_id=8a4938af-eef9-462f-b9aa-06b7520039c9&status=success&error_code=null&phone=84394375407&tracking_id=3b3285e0-e4b9-4ace-a8fc-d131d0b4f9de"
Example data (JSON format, for reference on structure):
{
"msg_id": "8a4938af-eef9-462f-b9aa-06b7520039c9",
"status": "success",
"error_code": null,
"phone": "84394375407",
"tracking_id": "3b3285e0-e4b9-4ace-a8fc-d131d0b4f9de"
}
✅ Response
- HTTP Code:
200 OK - The webhook returning
HTTP_CODE200 is considered successful - Error code list: Here
🛡️ Webhook Security
- IP Authentication: Only whitelisted IPs from our system are accepted.
📌 Notes
- If the webhook call fails, we will retry 2 more times, 30 seconds apart.
- The webhook response time must be less than 2 seconds. If it exceeds 2 seconds, it is considered a failure.
tracking_idonly appears for the batch send case, and is the same as theclient_message_idyou include with each message when calling the bulk send API, used to reconcile the status of each specific message.