Skip to Content
Public APIWebhooks

Webhooks

Webhooks push real-time events to your server as they happen — a customer replies, a message is delivered or read, someone taps a button, or a conversation is assigned. Every event carries a channel field ("whatsapp").

Configuring your webhook

Go to Settings → Developer → Configure Webhook, enter your HTTPS URL, and tick the events you want. You only receive events you have subscribed to.

Request format

Every event is delivered as an HTTP POST with this envelope:

{
  "event": "incoming_message",
  "timestamp": "2026-05-18T10:00:00Z",
  "data": { }
}
HeaderValue
Content-Typeapplication/json
X-Webhook-Eventthe event name
X-Webhook-Sourcesplashifypro

Respond with any 2xx status within 10 seconds. Non-2xx responses and timeouts are logged on our side; the event is not retried.

incoming_message

A customer sent a message to your business.

{
  "event": "incoming_message",
  "timestamp": "2026-05-18T10:00:00Z",
  "data": {
    "message_id": "wamid.HBgM...",
    "from": "919876543210",
    "conversation_id": "ee64970d-0539-4eb0-859d-2147859a604d",
    "type": "text",
    "text": "Hi, is my order shipped?",
    "channel": "whatsapp",
    "timestamp": "2026-05-18T10:00:00Z",
    "contacts": [
      { "profile": { "name": "Aditya" }, "wa_id": "919876543210" }
    ]
  }
}
FieldNotes
typetext, image, video, audio, document, location, …
textBody text, or the file name for media
media_urlPresent for media messages
contactsWhatsApp profile block

message_sent · message_delivered · message_read · message_failed

Delivery lifecycle of a message you sent.

{
  "event": "message_delivered",
  "timestamp": "2026-05-18T10:00:05Z",
  "data": {
    "message_id": "d58aeff7-a81c-47a7-9b67-f381e13f6c4e",
    "to": "919876543210",
    "status": "delivered",
    "channel": "whatsapp"
  }
}

message_failed additionally carries an error_message:

{
  "event": "message_failed",
  "timestamp": "2026-05-18T10:00:05Z",
  "data": {
    "message_id": "d58aeff7-...",
    "to": "919876543210",
    "status": "failed",
    "channel": "whatsapp",
    "error_message": "Message undeliverable"
  }
}

button_clicked

A customer tapped a template/interactive button. Fired alongside incoming_message.

{
  "event": "button_clicked",
  "timestamp": "2026-05-18T10:00:00Z",
  "data": {
    "message_id": "wamid.HBgM...",
    "conversation_id": "ee64970d-0539-4eb0-859d-2147859a604d",
    "from": "919876543210",
    "button_id": "confirm_order",
    "button_text": "Confirm Order",
    "channel": "whatsapp",
    "timestamp": "2026-05-18T10:00:00Z"
  }
}
FieldNotes
button_idThe button’s reply id / payload
button_textThe visible button label

team_member_assigned

A conversation was assigned to a team member — including when a chatbot hands the conversation over to a human agent.

{
  "event": "team_member_assigned",
  "timestamp": "2026-05-18T10:02:00Z",
  "data": {
    "conversation_id": "ee64970d-0539-4eb0-859d-2147859a604d",
    "contact": "919876543210",
    "assigned_to": "0b8074fd-510d-11f1-8b74-aa43648fa5e4",
    "assigned_name": "Jane Doe"
  }
}

Event reference

EventFires when
incoming_messageA customer sends a message
message_sentThe provider confirms the message was sent
message_deliveredThe provider confirms delivery
message_readThe recipient reads the message
message_failedThe message fails to deliver
button_clickedA customer taps a button
team_member_assignedA conversation is assigned to a team member (incl. bot→human handover)
Rate LimitsGet Users