Webhooks are user-defined HTTP callbacks that are triggered by specific events. Whenever that trigger event occurs, the WhatsApp Business API client sees the event, collects the data, and immediately sends a notification (HTTP request) to the Webhook URL.

Latest Update on Incoming Message Webhook Schema for Quick Reply

Note that effective from 10th September 2024, the old(message type - text) incoming message webhook schema will be deprecated and replaced by the new (message type - button & text type - payload) schema. Ensure that your webhook integration and chatbot code are updated to handle the new schema before this date.

For any questions or support, contact [email protected].

The below mentioned IP are Necore Server IP through which you will be receiving the Webhook Call Back URL. Request you to please Whitelist the same at your server end (if required).

Serial Number	Ip Addresses	Environment
1	3.109.231.61	Live
2	3.6.178.98	Live
3	13.127.49.56	Live
4	13.126.62.29	Live
5	139.59.22.149	UAT

We provide two types of Webhooks

Type	Request Type	What it does
Incoming message	POST	We will send user initiated content like 1.Text 2.Media 3.Video 4.Image 5.Document 6.Location
Delivery message	POST	We will delivery notification. 1. Sent 2.Delivered 3.Read 4. Failed

Incoming message: text

This webhook sends incoming messages as and when users send a text message. When user gives a reply to a previous message, then the context will be provided.

Method: POST

Parameters:

Parameter	Description	Data Type
ncmessage_id	ncmessage_id is unique id which is given when you send any message via PUSH api.	String
message_id	Unique message id	String
received_at	The time of status. The time when the message is received	Unix(Date - Time)
message_type	The type of message will be “button”	String
text_type	Represents the content of a button interaction. It includes payload and text. Payload is a unique identifier linked to the button action. Text is the label displayed on the button that the user clicks.	Object
from	The user mobile number	number

Incoming message: text Webhook

{
    "incoming_message": [
        {
            "context": {
                "message_id": "XXXXXX",
                "ncmessage_id": "XXXXXX"
            },
            "from": "91XXXXXXXXXX",
            "from_name": "🙂",
            "message_id": "wamid.XXXX",
            "message_type": "text",
            "received_at": "1724226706",
            "text_type": {
                "text": "I’m Interested"
            },
            "to": "912249757556"
        }

Incoming Message: Media

This webhook sends incoming messages as and when users send media messages. Media message can be 3 type -

Image
Audio
Video

When the user gives a reply to a previous message, then the context will be provided.

Method: POST

Parameter	Description	Data Type
ncmessage_id	ncmessage_id is unique id which is given when you send any message via PUSH api.	String
message_id	Unique message id	String
received_at	The time of status. The time when the message is received	Unix (Date - Time)
mesage_type	The type of message will be -IMAGE,VIDEO,DOCUMENT	String
id	This will be media id. You can get the media from Media API.	String
caption	This will contain the caption of file name	String
from	The user mobile number	number

Incoming Message: Media Webhook

{
    "incoming_message": 
        [
          {
          "message_id": "ABEGkZlgQyWAAgo-sOme7WUxlHHq",
          "from": "919960432580",
          "from_name": "udayan",
          "received_at": "1567091670",
          "context": 
              {
              "ncmessage_id": null,
              "message_id": null
              },
          "message_type": "IMAGE",
          "image_type": 
              {
              "sha256":
              "dd04cf3f58d890729201bbfa100c22ba02ab2a9353de793eddaf9fbbfdac9cbb",
              "mime_type": "image\/jpeg",
              "id": "aa41ac0d-2eb4-4d4a-a212-03f3c0e2001d"
              "to": "912249757556"
              }
            }
          ]
}

Incoming message: location

This webhook send incoming message as and when user send a location.

Location data will contain lat and long.

When user gives a reply to a previous message then context will be provided.

Method: POST

Parameters:

Parameter	Description	Data Type
ncmessage_id	ncmessage_id is unique id which is given when you send any message via PUSH api.	String
message_id	Unique message id	String
received_at	The time of status. The time when the message is received	Unix(Date - Time)
mesage_type	The type of message will be “location”	String
latitude	The latitude of location	String
longitude	The longitude of location	String
from	The user mobile number	number

Incoming message location Webhook

{ 
    "incoming_message": [{ 
        "message_id": "ABEGkZlgQyWAAhC3CZb1ttzQo0mvQBbL2pFk", 
        "from": "919960432580", 
        "from_name": "udayan",
        "received_at": "1567092229", 
        "context": { 
            "ncmessage_id": null, 
            "message_id": null 
        }, 
        "message_type": "LOCATION", 
        "location_type": { 
            "address": "Dosti Pinnacle, Unit No. G1, Plot No. E7, Th\u0101ne, 
Mah\u0101r\u0101shtra 400604", 
            "latitude": 19.198988196033, 
            "name": "Passport Seva Kendra", 
            "url": "http:\/\/www.passportindia.gov.in", 
            "longitude": 72.948932751057
            "to": "912249757556"
        } 
    }]

Incoming message Quick Reply Webhook

{
  "data": {
    "incoming_message": [
      {
        "context": {
          "message_id": "xapi csv",
          "ncmessage_id": "2fa02b33-3fb4-4429-882a-e07b67ed233f"
        },
        "from": "919321926429",
        "from_name": "Anil Shukla",
        "message_id": "wamid.HBgMOTE5MzIxOTI2NDI5FQIAEhggQjIzMTM1RUVFNjU5MUREQTY0RTlGQTZGNUM5R\nUM5QzcA",
        "message_type": "button",
        "received_at": "1718994527",
        "text_type": {
          "payload": "Product_id",
          "text": "qrpayload " //Business Developer-defined payload
        },
        "to": "912249757556"
      }
    ]
  }
}

Delivery Message Webhook

This enables developers receive the events as and when it happens.

Delivery Notification send the delivery notification such as (Sent, Delivered, Read)

The delivery notification will be sent in batch. There is no fixed batch size.

Parameter	Description	Data Type
ncmessage_id	ncmessage_id is unique id which is given when you send any message via PUSH api.	String
recipient	The user mobile number	Number
status	The status of message. There will be 4 status. a) Read b) Delivered c) Sent d) Failed	String
status_remark	If the message are failed then failed remark will be given	String
received_at	The time of status	Unix (date-time)
source	The source will be return what you have passed at time of PUSH API.	String

Read Event Webhook Payload

{ 
"delivery_status":[ 
        { 
                "ncmessage_id":"fa9d647a-c8d7-423e-bd27-7d2ca2875d12", 
                "phoneNumber": "912249757556",
                "received_at": "1694500928",
                "recipient":"919999999999", 
                "status":"read", 
                "status_remark":"", 
                "received_at":"1567091670", 
                "source":"fa9d647a-c8d7-423e-bd27-7d2ca2875dc1", 
        } 
        ] 
}

Clicked Event Webhook Payload

{
 "delivery_status": [
 {
 "ncmessage_id": "022bc5a0-193f-4f87-9502-f2f00279084d",
 "recipient": "916361467892",
 "status": "clicked",
 "status_remark": "",
 "source": "source test",
 "received_at": "1694502984",
 "x-apiheader": "xpi test",
 "phoneNumber": "2249757556",
 "useragent": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Mobile Safari/537.36",
 "url": "https://www.youtube.com/",
 "shorturl": "i0UNPlW"
 }
 ]
}

We have 5 Statusses
Sent, delivered, read, clicked, failed, Not Sent.
Failed and Not Sent would have status_remarks for reasons of not sending or getting failed.

Forms/Flows Webhook Response

"data": {
"incoming_message": [
{
"context": {
"message_id": "",
"ncmessage_id": ""
},
"from": "919049871578",
"from_name": "Hitesh",
"interactive_type": {
"nfm_reply": {
"body": "Sent",
"name": "flow",
"response_json": "{"flow_token":"AQAAAAACS5FpgQ_cAAAAAD0QI3s.","screen_1_TextInput_0":"gfh"}"
},
"type": "nfm_reply"
},
"message_id": "wamid.HBgMOTE5MDQ5ODcxNTc4FQIAEhggMzE0RDZEQTE5REQxRTRCQUQwRjREOTFGRDhFOTQ5RjgA",
"message_type": "INTERACTIVE",
"received_at": "1709634338",
"to": "919867644673"
}
]
}

Order Details Payment Webhook

The status field indicates whether a payment has been successfully captured or is still pending.

Type: string

Required: Yes

There are two possible values:

Payment Captured: Payment has been successfully completed.

Webhook Response:

{
    "delivery_status": [
        {
            "ncmessage_id": "ce689059-8399-48c4-8417-15ce6f0aa683",
            "payment": {
                "amount": {
                    "offset": 100,
                    "value": 100
                },
                "currency": "INR",
                "reference_id": "ID112123",
                "transaction": {
                    "amount": {
                        "offset": 100,
                        "value": 100
                    },
                    "created_timestamp": 1742991595,
                    "currency": "INR",
                    "fees": {
                        "payment_method_fee": {
                            "offset": 100,
                            "value": 3
                        }
                    },
                    "id": "order_QBPtMagbi8hneS",
                    "status": "success",
                    "type": "razorpay",
                    "updated_timestamp": 1742991595
                }
            },
            "phoneNumber": "919867644673",
            "received_at": "1742991596",
            "recipient": "918984519399",
            "source": "",
            "status": "captured",
            "status_remark": "",
            "type": "payment",
            "x-apiheader": "custom_data"
        }
    ]
}

Payment Pending: Payment has been attempted, but has not yet received a success confirmation.

This response indicates that the payment attempt was made, but the final success confirmation has not yet been received. In this case the payment attempt failed due to incorrect UPI pin entered but the user can retry.

Webhook Response

{
    "delivery_status": [
        {
            "ncmessage_id": "ce689059-8399-48c4-8417-15ce6f0aa683",
            "payment": {
                "amount": {
                    "offset": 100,
                    "value": 100
                },
                "currency": "INR",
                "reference_id": "ID112123",
                "transaction": {
                    "amount": {
                        "offset": 100,
                        "value": 100
                    },
                    "created_timestamp": 1742991563,
                    "currency": "INR",
                    "error": {
                        "code": "BAD_REQUEST_ERROR",
                        "reason": "incorrect_pin"
                    },
                    "fees": {
                        "payment_method_fee": {
                            "offset": 100,
                            "value": 0
                        }
                    },
                    "id": "order_QBPsflnhFi2CDP",
                    "status": "failed",
                    "type": "razorpay",
                    "updated_timestamp": 1742991563
                }
            },
            "phoneNumber": "919867644673",
            "received_at": "1742991564",
            "recipient": "918984519399",
            "source": "",
            "status": "pending",
            "status_remark": "",
            "type": "payment",
            "x-apiheader": "custom_data"
        }
    ]
}

Standard Flow response whenever a customer fills a response on the designated form.

Incase You are Facing Any Issue, Feel Free to write to us at [email protected]

CTWA Webhook

This webhook is triggered when a user clicks on a Click-to-WhatsApp ad (CTWA) and initiates a chat on WhatsApp with the business.

📘
Important point to remember
To successfully log a conversion or event via Netcore's Conversion API, you must givr any one of the following from the webhook:

ctwa_clid – the Click ID found under referral.ctwa_clid, which ties the user back to the specific ad click OR

from – the user’s WhatsApp phone number, used as a fallback identifier

Without one of these two identifiers, the Conversion API will be unable to map the event to a CTWA ad campaign.

{
  "incoming_message": [
    {
      "context": {
        "message_id": "",
        "ncmessage_id": ""
      },
      "from": "6285112345678",
      "from_name": "Alexandra D",
      "message_id": "wamid.HBgNNjI4MDEyMzQ1Njc4OVUCABIYIEXAMPLE123EXAMPLE456EXAMPLEAA==",
      "message_type": "TEXT",
      "received_at": "1753899999",
      "referral": {
        "body": "LIMITED OFFER! 🎉\n\nJoin now and get a welcome surprise. T&Cs apply.",
        "ctwa_clid": "XyZ12345CLID67890abcDEFEXAMPLExyz",
        "headline": "Welcome Gift for First-Time Customers",
        "media_type": "image",
        "source_id": "120255555555555555",
        "source_type": "ad",
        "source_url": "https://fb.me/exampleCampaignLink",
        "thumbnail_url": "https://cdn.example.com/media/thumbnails/welcome-offer.jpg",
        "video_url": "https://facebook.com/BrandPage/videos/1234567890123456/",
        "welcome_message": {
          "text": "Hi there! 👋 Welcome to our official account. How can we help you today?"
        }
      },
      "text_type": {
        "text": "Hi! I saw your ad and would love to know more 😄"
      },
      "to": "6287888999000"
    }
  ]
}

Incoming Message Order (Multi-Product)

This webhook is triggered when a customer sends their shopping cart to the business using WhatsApp. It includes one or more products, and optionally a free‑form text note.

Method: POST

Parameters

Parameter	Description	Data Type
`contacts`	An array of contact objects. Always includes the customer’s profile and `wa_id`	Array
`messages`	An array of message objects. Includes one `order` message	Array
`messages[].from`	Customer's WhatsApp number	String
`messages [].id`	Unique message ID	String
message[] .type	Set to "order"	String
message[].timestamp	Unix timestamp when the order was sent	String
messages[].order.catalog_id	ID of catalog the products belong to	String
messages[].order.product_items	Array of ordered items	Array
messages[].order.product_items[].product_retailer_id	SKU or product ID	String
messages[].order.product_items[].quantity	Quantity ordered	Integer
messages[].order.product_items[].item_price	Price per unit in smallest currency unit	Integer
messages[].order.product_items[].currency	Currency code (e.g., INR)	String
messages[].order.text	(optional) Free‑form user message accompanying the order	String

Note on product limits:

When the cart contains a single product, your integration may enforce a business rule that limits the number of products (e.g., quantity ≤ 1).
For multiple‑product orders, there is no enforced limit on the number of different products—customers can include multiple product_items.

Example Webhooks

Multi‑Product Order (no text):

{
  "contacts": [{
    "profile": { "name": "akshay" },
    "wa_id": "919664593753"
  }],
  "messages": [{
    "from": "919664593753",
    "id": "ABEGkZZkWTdTAhB4dixZFKudYYzef6MMVH3b",
    "order": {
      "catalog_id": "483833899912685",
      "product_items": [
        {
          "currency": "INR",
          "item_price": 249,
          "product_retailer_id": "JHAJI-OAL-250",
          "quantity": 2
        },
        {
          "currency": "INR",
          "item_price": 349,
          "product_retailer_id": "JHAJI-KAJU-350",
          "quantity": 1
        }
      ]
    },
    "timestamp": "1654838618",
    "type": "order"
  }]
}

Multi‑Product Order with user text:

{
  "contacts": [{
    "profile": { "name": "akshay" },
    "wa_id": "919664593753"
  }],
  "messages": [{
    "from": "919664593753",
    "id": "ABEGkZZkWTdTAhB1qVwanDRO2vbW6H4IgDhX",
    "order": {
      "catalog_id": "483833899912685",
      "product_items": [
        {
          "currency": "INR",
          "item_price": 249,
          "product_retailer_id": "JHAJI-OAL-250",
          "quantity": 2
        },
        {
          "currency": "INR",
          "item_price": 349,
          "product_retailer_id": "JHAJI-KAJU-350",
          "quantity": 1
        }
      ],
      "text": "Please gift wrap these items"
    },
    "timestamp": "1654838957",
    "type": "order"
  }]
}

Workflow

A customer adds multiple items to their WhatsApp cart (via interactive product messages) and sends the cart.
WhatsApp triggers an order webhook containing all chosen products.
Your business system receives each product_item, handling multiple SKUs and quantities accordingly.
If text is included, treat it as a special instruction and include it in your order workflow.

Standard Flow response whenever a customer fills a response on the designated form.

In case you are facing any issue, feel free to write to us at [email protected]

Send Location Request Message Webhook

When a user shares their location in response to a Location Request Message, Netcore sends a webhook notification to your configured endpoint. This webhook contains the location details provided by the user.

Webhook Payload Example

{
  "incoming_message": [
    {
      "context": {
        "message_id": "wamid.HBgMOTE2MjY3NzI1MDk5NDQkEwM0FGODc0AA==",
        "ncmessage_id": "9f520263-ccd0-4bf9-8634-1d6222346f23",
        "x-apiheader": "custom_data"
      },
      "from": "<10 digit mobile with country code>",
      "from_name": "Vishal",
      "location_type": {
        "latitude": "18.973591949103",
        "longitude": "72.999067939818",
        "name": "Shri Atal Bihari Vajpayee Trans Hbr Link, Maharashtra 410206, India",
        "address": "Shri Atal Bihari Vajpayee Trans Hbr Link, Maharashtra 410206, India"
      },
      "message_id": "wamid.HBgMOTE2MjY3NzI1MDk5FQIAEhggNEMyQjRCOUQy",
      "message_type": "LOCATION",
      "received_at": "1756305600",
      "to": "912249757556"
    }
  ]
}

WhatsApp Webhooks: Callback URL

We provide two types of Webhooks

Incoming message: text

Method: POST

Parameters:

Incoming message: text Webhook

Incoming Message: Media

Incoming Message: Media Webhook

Incoming message: location

Incoming message location Webhook

Incoming message Quick Reply Webhook

Delivery Message Webhook

Read Event Webhook Payload

Clicked Event Webhook Payload

Forms/Flows Webhook Response

Order Details Payment Webhook

Webhook Response

CTWA Webhook

📘
Important point to remember

Incoming Message Order (Multi-Product)

Note on product limits:

Example Webhooks

Multi‑Product Order (no text):

Multi‑Product Order with user text:

Workflow

Send Location Request Message Webhook

Webhook Payload Example

We provide two types of Webhooks

Incoming message: text

Method: POST

Parameters:

Incoming message: text Webhook

Incoming Message: Media

Incoming Message: Media Webhook

Incoming message: location

Incoming message location Webhook

Incoming message Quick Reply Webhook

Delivery Message Webhook

Read Event Webhook Payload

Clicked Event Webhook Payload

Forms/Flows Webhook Response

Order Details Payment Webhook

Webhook Response

CTWA Webhook

📘Important point to remember

Incoming Message Order (Multi-Product)

Note on product limits:

Example Webhooks

Multi‑Product Order (no text):

Multi‑Product Order with user text:

Workflow

Send Location Request Message Webhook

Webhook Payload Example

📘
Important point to remember