Webhooks API Reference

Webhooks deliver real-time HTTP POST notifications to your endpoint when events occur in your BIK account. Subscribe to message status updates, customer interactions, agent assignments, and store activity across all supported channels.

---

Getting Started

How Webhooks Work

When an event occurs in your account, we send an HTTP POST request to your configured webhook URL with a JSON payload containing event details.

You can configure your webhook in the Webhooks.

Supported Channels

Channel	Description
whatsapp	WhatsApp Business API
email	Email communications
sms	SMS messages
instagram	Instagram Direct
messenger	Facebook Messenger
rcs	Rich Communication Services
webpush	Web push notifications

Message Sources

The owner field indicates where the message originated:

Owner	Source	Description
AGENT	CRM	Sent by an agent from inbox
MERCHANT	CRM	Sent by merchant from inbox
BOT	Journey	Sent by automated journey
CAMPAIGN	Campaign	Sent via broadcast campaign
TEST_CAMPAIGN	Campaign	Sent via test campaign
DEV_API	Dev API	Sent via Developer API

---

Payload Structure

All webhook payloads are JSON arrays:

[{
  "eventName": "message-status-update",
  "eventInfo": { ... },
  "storeId": "your_store_id",
  "customerDetails": {
    "customerId": 12345678,
    "firstName": "John",
    "lastName": "Doe"
  },
  "id": "unique_event_id"
}]

Top-Level Fields

Field	Type	Description
eventName	string	Event type identifier
eventInfo	object	Event-specific data
storeId	string	Your store/account identifier
customerDetails	object	Customer information
id	string	Unique webhook event ID

---

Event Categories

Online Store Events

Events triggered by customer activity on your online store.

Event Name	Description
productViewed	Customer viewed a product
addToCart	Item added to cart
removeFromCart	Item removed from cart
addedToWishlist	Item added to wishlist
keywordSearched	Customer searched for a keyword
usedAPromoCode	Promo code applied
orderCancelled	Order was cancelled

Operational Events

Events related to CRM operations and agent activities.

Event Name	Description
assignedAgent	Agent assigned to conversation
reassignedAgent	Conversation reassigned to another agent
customerCreated	New customer profile created

Channel Events

Events related to messaging across channels.

Event Name	Description
message-status-update	Message status changed (sent/delivered/read/failed)
incomingMessage	Customer sent a message
linkClicked	Customer clicked a link in message
qrbClicked	Customer clicked a quick reply button
optedOut	Customer opted out of messages

---

Event Reference

message-status-update

Triggered when a message status changes.

Status Values: sent, delivered, read, failed

Field	Type	Description
messageId	string	Unique message identifier
createdAt	string	ISO 8601 timestamp
channelId	string	Channel: whatsapp, email, sms, instagram, messenger
status	string	Message status
message	string	Message content
failureReason	string	Failure reason (null if successful)
owner	string	Message source (see table above)
ownerId	string	Sender identifier
assetValue	string	Channel asset (e.g., phone number)
ticketId	string	Ticket/conversation ID
templateId	string	Template ID (if applicable)
templateCategory	string	Template category: MARKETING, UTILITY

---

incoming-message

Triggered when a customer sends a message.

Field	Type	Description
messageId	string	Unique message identifier
createdAt	string	ISO 8601 timestamp
channelId	string	Channel identifier
message	string	Message text
mediaType	string	Media type (if applicable)
media	object	Media details (if applicable)
location	object	Location data (if applicable)
order	object	Order data (if applicable)
referral	object	Ad referral data (if applicable)
owner	string	Always CUSTOMER
ownerId	string	Customer ID
assetValue	string	Customer phone/email
ticketId	string	Ticket ID (null if new conversation)

---

assignedAgent

Triggered when an agent is assigned to a conversation.

Field	Type	Description
assignedAgentId	string	Agent ID
agentName	string	Agent name
ticketId	string	Ticket ID
chatSessionId	string	Chat session ID
ticketCreatedAt	string	Ticket creation timestamp
triggeredDate	string	Assignment timestamp
timeToAssign	number	Seconds to assignment
nonWorkingHoursSinceCreated	number	Non-working hours elapsed
isWhatsappCallTicket	boolean	WhatsApp call ticket flag
merchantLabelNames	array	Applied labels
aiIntents	array	Detected customer intents

---

reassignedAgent

Triggered when a conversation is reassigned.

Field	Type	Description
previousAgentId	string	Previous agent ID
previousAgentName	string	Previous agent name
newAgentId	string	New agent ID
newAgentName	string	New agent name
ticketId	string	Ticket ID
triggeredDate	string	Reassignment timestamp
reason	string	Reassignment reason

---

customerCreated

Triggered when a new customer is created.

Field	Type	Description
customerId	string	Customer ID
createdAt	string	Creation timestamp
source	string	Creation source

---

optedOut

Triggered when a recipient opts out of receiving messages.

Field	Type	Description
templateId	string	Template ID that triggered opt-out
userChannelId	string	User's channel identifier
channel	string	Messaging channel
messageId	string	Message ID
broadcastId	number	Broadcast campaign ID (if applicable)
eventSource	string	Source of the event

---

linkClicked

Triggered when a customer clicks a tracked link in a message.

Field	Type	Description
messageId	string	Original message ID
linkUrl	string	URL that was clicked
channel	string	Messaging channel
clickedAt	string	Click timestamp

---

qrbClicked

Triggered when a customer clicks a quick reply button.

Field	Type	Description
messageId	string	Original message ID
buttonId	string	Button identifier
buttonText	string	Button text/label
channel	string	Messaging channel

---

Online Store Events

These events are triggered by customer activity on your online store.

pageViewed

Field	Type	Description
pageUrl	string	URL of the viewed page
pageTitle	string	Title of the page
referrer	string	Referrer URL

productViewed

Field	Type	Description
productId	string	Product identifier
productName	string	Product name
productPrice	number	Product price
currency	string	Price currency

addToCart / removeFromCart

Field	Type	Description
productId	string	Product identifier
productName	string	Product name
quantity	number	Quantity added/removed
price	number	Product price

addedToWishlist

Field	Type	Description
productId	string	Product identifier
productName	string	Product name

keywordSearched

Field	Type	Description
keyword	string	Search term
resultsCount	number	Number of results shown

usedAPromoCode

Field	Type	Description
promoCode	string	Promo code used
discountAmount	number	Discount applied

orderCancelled

Field	Type	Description
orderId	string	Order identifier
reason	string	Cancellation reason
cancelledAt	string	Cancellation timestamp

---

Example Payloads

Message Sent

[{
  "eventName": "message-status-update",
  "eventInfo": {
    "messageId": "wamid.HBgMOTE5NjI5NzA4NzgzFQIAERgSMEUxMURBMUY4N0Q1NEZDRDg0AA==",
    "createdAt": "2025-12-19T13:00:51.657Z",
    "channelId": "whatsapp",
    "status": "sent",
    "message": "Your order has been confirmed.",
    "failureReason": null,
    "owner": "BOT",
    "ownerId": "journey_123",
    "assetValue": "+91XXXXXXXXXX",
    "ticketId": "33678570",
    "templateId": "order_confirmation",
    "templateCategory": "UTILITY"
  },
  "storeId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "customerDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "customerId": 12345678
  },
  "id": "7dab423c-46e4-406a-8f50-45221189731b"
}]

Message Delivered

[{
  "eventName": "message-status-update",
  "eventInfo": {
    "messageId": "wamid.HBgMOTE5NjI5NzA4NzgzFQIAERgSMkUyOUQ5RDhCQUE5NTY0NzYxAA==",
    "createdAt": "2025-12-19T13:00:19.020Z",
    "channelId": "whatsapp",
    "status": "delivered",
    "message": "Your order has been confirmed.",
    "failureReason": null,
    "owner": "BOT",
    "ownerId": "journey_123",
    "assetValue": "+91XXXXXXXXXX",
    "ticketId": "33678570"
  },
  "storeId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "customerDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "customerId": 12345678
  },
  "id": "dd7e9f2e-6479-46fd-91ce-1f80f49c6ee9"
}]

Message Read

[{
  "eventName": "message-status-update",
  "eventInfo": {
    "messageId": "wamid.HBgMOTE5NjI5NzA4NzgzFQIAERgSMkUyOUQ5RDhCQUE5NTY0NzYxAA==",
    "createdAt": "2025-12-19T13:00:25.000Z",
    "channelId": "whatsapp",
    "status": "read",
    "message": "Your order has been confirmed.",
    "failureReason": null,
    "owner": "BOT",
    "ownerId": "journey_123",
    "assetValue": "+91XXXXXXXXXX",
    "ticketId": "33678570"
  },
  "storeId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "customerDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "customerId": 12345678
  },
  "id": "7103d05a-c230-499d-a9c6-6aea7b579dbb"
}]

Message Failed

[{
  "eventName": "message-status-update",
  "eventInfo": {
    "messageId": "wamid.HBgMOTE5NjI5NzA4NzgzFQIAERgSMkUyOUQ5RDhCQUE5NTY0NzYxAA==",
    "createdAt": "2025-12-19T13:00:30.000Z",
    "channelId": "whatsapp",
    "status": "failed",
    "message": "Your order has been confirmed.",
    "failureReason": "Message failed to send. Recipient phone number not on WhatsApp.",
    "owner": "BOT",
    "ownerId": "journey_123",
    "assetValue": "+91XXXXXXXXXX",
    "ticketId": "33678570",
    "templateId": "order_confirmation",
    "templateCategory": "UTILITY"
  },
  "storeId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "customerDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "customerId": 12345678
  },
  "id": "a8f3e2c1-5b4d-4a9e-8c76-2d1f0e9b8c7a"
}]

Incoming Message

[{
  "eventName": "incoming-message",
  "eventInfo": {
    "messageId": "wamid.HBgMOTE5NjI5NzA4NzgzFQIAEhgWM0VCMDQwQjkwMjRCM0NERkZFMkU5OQA=",
    "createdAt": "2025-12-19T13:01:00.000Z",
    "channelId": "whatsapp",
    "message": "track my order",
    "mediaType": null,
    "media": null,
    "location": null,
    "order": null,
    "referral": null,
    "owner": "CUSTOMER",
    "ownerId": "12345678",
    "assetValue": "+91XXXXXXXXXX",
    "ticketId": null,
    "customerId": "12345678"
  },
  "storeId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "customerDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "customerId": 12345678
  },
  "id": "98b3fdb0-2a9b-45ab-b006-9cfc9b516344"
}]

Agent Assigned

[{
  "eventName": "assignedAgent",
  "eventInfo": {
    "assignedAgentId": "235658",
    "agentName": "Agent Name",
    "ticketId": "33678570",
    "chatSessionId": "33678570",
    "ticketCreatedAt": "2025-12-19T06:31:42.812Z",
    "triggeredDate": "2025-12-19T13:00:17.201552",
    "timeToAssign": 23315.108,
    "nonWorkingHoursSinceCreated": 0,
    "isWhatsappCallTicket": false,
    "merchantLabelNames": ["product search", "checkout"],
    "aiIntents": ["Product Discovery", "Order Tracking"]
  },
  "storeId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "customerDetails": {
    "customerId": "12345678"
  }
}]

Opted Out

[{
  "eventName": "optedOut",
  "storeId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "customerId": "6840089",
  "eventInfo": {
    "templateId": "7rlzTu4LKZpRPHoiROSQ",
    "userChannelId": "221036",
    "channel": "whatsapp"
  },
  "channel": "whatsapp",
  "messageId": "wamid.HBgMOTE5NDYwMzM2Nzc3FQIAERgSNDRCQTU5NEI1NEE3Mzc3NjBCAA==",
  "broadcastId": 174183,
  "eventSource": "Campaigns",
  "createdAt": "2025-12-19T11:10:32.609Z",
  "id": "optedOut-221036"
}]

---

Security

Authorization Header

All webhook requests include an authorization header:

Authorization: Basic <your_authorization_key>

tip

Verify this matches your configured key to authenticate incoming webhooks and reject unauthorized requests.

---