Event Reference
All outbound webhooks share a common envelope. The data field varies by eventType.
Common envelope
| Field | Type | Description |
|---|---|---|
eventType | string | message, status, payment, order, media.ready, or test |
userId | number | ChatYug tenant user ID |
wabaId | string | WhatsApp Business Account ID |
phoneNumberId | string | Phone number that received or sent the event |
eventId | string | Idempotency key (typically Meta message or status ID) |
occurredAt | string | ISO 8601 UTC timestamp when ChatYug dispatched the event |
data | object | Event-specific payload (see below) |
eventType: message
Fired when a customer sends an inbound message.
{
"eventType": "message",
"userId": 42,
"wabaId": "100000000000002",
"phoneNumberId": "100000000000001",
"eventId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==",
"occurredAt": "2026-07-13T07:00:00.000Z",
"data": {
"metadata": {
"display_phone_number": "+91 98765 43210",
"phone_number_id": "100000000000001"
},
"contacts": [
{
"profile": { "name": "Rahul Sharma" },
"wa_id": "919876543210"
}
],
"message": {
"from": "919876543210",
"id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==",
"timestamp": "1720856400",
"type": "text",
"text": { "body": "Hello, I need help with my order" }
}
}
}The message object follows Meta's inbound message schema. Types include text, image, document, interactive (button/list replies), order, and flow submissions (nfm_reply).
For image / video / audio / document, the Meta payload includes only a media id (not a downloadable URL). Wait for media.ready (below) or call GET /api/external/messages/:chatyugMessageId/media after you discover the ChatYug message ID from the conversations API.
eventType: media.ready
Fired after ChatYug downloads inbound media from Meta and stores it under /received_media/. Use this for a stable HTTPS file URL. The earlier message event is unchanged (Meta-shaped) for backward compatibility.
{
"eventType": "media.ready",
"userId": 42,
"wabaId": "100000000000002",
"phoneNumberId": "100000000000001",
"eventId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==_media",
"occurredAt": "2026-07-13T07:00:02.000Z",
"data": {
"metaMessageId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==",
"chatyugMessageId": "223900",
"mediaType": "image",
"mimeType": "image/jpeg",
"mediaPath": "/received_media/919586753155/image_1720856402000_123456789.jpg",
"mediaUrl": "https://chatyug.com/received_media/919586753155/image_1720856402000_123456789.jpg",
"caption": "Invoice photo"
}
}| Field | Description |
|---|---|
metaMessageId | Same as Meta message.id from the preceding message event |
chatyugMessageId | ChatYug Message_Id (use with GET /api/external/messages/:id/media) |
mediaUrl | Absolute HTTPS URL served by ChatYug (preferred for download) |
mediaPath | Relative path under the ChatYug public root |
Recommended client flow: handle message → if type is media, wait for media.ready matching metaMessageId → fetch data.mediaUrl. Alternatively poll GET /api/external/conversations/:id/messages until mediaPending is false and mediaUrl is an https:// link.
eventType: status
Fired when an outbound message status changes.
{
"eventType": "status",
"userId": 42,
"wabaId": "100000000000002",
"phoneNumberId": "100000000000001",
"eventId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==",
"occurredAt": "2026-07-13T07:00:05.000Z",
"data": {
"metadata": {
"display_phone_number": "+91 98765 43210",
"phone_number_id": "100000000000001"
},
"status": {
"id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==",
"status": "delivered",
"timestamp": "1720856405",
"recipient_id": "919876543210"
}
}
}status.status values include sent, delivered, read, and failed. Meta payment updates are not sent as status — see payment below.
eventType: payment
Fired when Meta delivers a WhatsApp Payments status update (statuses[].type === "payment"). Same HMAC (X-Chatyug-Signature) and idempotency headers as other events. Stable eventId: payment:{reference_id}:{transaction.id}:{status}.
{
"eventType": "payment",
"userId": 42,
"wabaId": "100000000000002",
"phoneNumberId": "100000000000001",
"eventId": "payment:AMUL-10042:pg_order_abc:captured",
"occurredAt": "2026-10-14T07:00:05.000Z",
"data": {
"metadata": {
"display_phone_number": "+91 98765 43210",
"phone_number_id": "100000000000001"
},
"reference_id": "AMUL-10042",
"status": "captured",
"amount": { "value": 11000, "offset": 100 },
"currency": "INR",
"transaction": {
"id": "pg_order_abc",
"pg_transaction_id": "payu_txn_xyz",
"type": "payu",
"status": "success",
"method": { "type": "upi" }
},
"recipient_id": "919876543210",
"timestamp": "1720856405",
"raw": { }
}
}data.raw is the untouched Meta status object. Reconcile with your payment gateway using reference_id. After capture, send order_status updates to the customer.
eventType: order
Fired when a customer submits a WhatsApp catalog cart order.
{
"eventType": "order",
"userId": 42,
"wabaId": "100000000000002",
"phoneNumberId": "100000000000001",
"eventId": "900000000000003",
"occurredAt": "2026-07-13T07:01:00.000Z",
"data": {
"metadata": {
"display_phone_number": "+91 98765 43210",
"phone_number_id": "100000000000001"
},
"contacts": [
{
"profile": { "name": "Rahul Sharma" },
"wa_id": "919876543210"
}
],
"order": {
"catalog_id": "900000000000003",
"product_items": [
{
"product_retailer_id": "SKU-1001",
"quantity": 2,
"item_price": 499,
"currency": "INR"
}
]
},
"chatyug": {
"order_id": 135,
"order_number": "135",
"items_count": 2,
"total_amount": 998,
"currency": "INR",
"thumbnail_url": "https://cdn.example.com/sku-1001.jpg",
"items": [
{
"product_retailer_id": "SKU-1001",
"product_name": "Sample Product",
"quantity": 2,
"item_price": 499,
"currency": "INR",
"image_url": "https://cdn.example.com/sku-1001.jpg"
}
]
}
}
}data.order is the raw Meta cart. Additive data.chatyug adds ChatYug order_id, enriched product names/images, and totals for UI parity with WhatsApp’s sent-cart card. Prefer data.chatyug.items when rendering; keep reading data.order.product_items for Meta-compatible parsers.
eventType: test
Sent from Webhook Settings when you click "Send test event".
{
"eventType": "test",
"userId": 42,
"wabaId": "100000000000002",
"phoneNumberId": "test-phone-number-id",
"eventId": "test_1720856400000",
"occurredAt": "2026-07-13T07:00:00.000Z",
"data": {
"message": "Webhook test event from Chatyug portal",
"businessName": "Example Business Pvt Ltd"
}
}