Desk Platform API v1
Desk Platform API
Platform API
Version 1
Platform API

Webhooks for Bots

Copy link

When creating a custom bot on the Sendbird Dashboard, the webhook URL of your server should be registered in Sendbird Desk to integrate your chatbot or a third-party bot. Once registered, your server will receive HTTP POST requests from the Desk server in the form of the response containing information on all events related to a bot that occur within the application.

Note: You can set a different webhook URL for each bot using the Bot API or in Settings > Desk > Bots of your dashboard.


Copy link

You can configure a webhook endpoint URL and other relevant settings for each bot in Settings > Desk > Bots of your dashboard.

Webhook endpoint requirements

Copy link

HTTP POST requests with JSON payloads are sent to your webhook endpoint upon specific events in your Sendbird application.

  • The endpoint must support HTTP/1.1 and keep-alive.
  • The endpoint needs to respond to POST requests.
  • The endpoint needs to parse JSON payloads.

By default, Sendbird server sends an HTTP POST request and waits for a response from your webhook endpoint for 1 second. The server sends the same POST request up to three times until it receives a response. To avoid too many requests, you should implement the endpoint to respond immediately to the server with a 200 OK response.

Note: When you need a process or function which handles webhook payloads, it should be implemented to be executed asynchronously from that of which responds to the server. If they are executed synchronously, it can cause the endpoint to stop working properly when many events happen on your application.


Copy link

HTTP POST requests from Sendbird server will include the following headers.

content-type: application/json
x-hub-signature: {x_hub_signature}


Copy link

Used as a request header to ensure that the source of the request comes from Sendbird server and the request is not altered by external influences. Based on both the POST request body and your API token, the value of the x-hub-signature starting with sha1= is generated by SHA-1 encryption on the Sendbird server side. To verify the request on your server side, create a comparison value exactly the same way as Sendbird server does, and then check if the result is equal to the value of the x-hub-signature.

# Python sample: how to check the x-hub-signature header value
secret_key = bytes(secret_key, 'utf‐8')
http_request_body = bytes(http_request_body, 'utf‐8')
x_hub_signature_for_comparision = 'sha1=' +, http_request_body, hashlib.sha1).hexdigest()
assert signature_to_compare == 'x_hub_signature'   # Check if the value of the 'x-hub-signature' request header is the same as the comparison value you've created.

Note: Upon creation, each bot is given a secret key which can be found on your dashboard. The secret key is encrypted and used to generate a value of x-hub-signature header for HTTP requests.

Data structure

Copy link

All webhook events depend on the following data structure.

    "eventType": (String),
    "botWebhookEvent": (Object),
    "ticket": (Object)

List of properties

Copy link
Property nameTypeDescription



The type of the event.


nested object

An object that contains information about the bot and the chat message from a customer.


nested object

An object that contains information about the ticket.

Webhook events

Copy link
EventTriggered when


A bot receives the message sent by a customer.


Copy link

The following shows a webhook payload of a MESSAGE.RECEIVED event.

    "eventType": "MESSAGE.RECEIVED",
    "botWebhookEvent": {
        "id": 115,
        "bot": 63,
        "status": "SENT",
        "webhookUrl": "",
        "createdAt": "2021-02-18T01:00:36.904553Z",
        "updatedAt": "2021-02-18T01:00:36.904513Z",
        "chatMessage": {
            "id": 167948,
            "ticket": 154565,
            "userSendbirdId": "tree",
            "userType": "CUSTOMER",
            "createdAt": "2021-02-18T01:00:36.571000Z",
            "message": "Hi, can I reset my password?"
    "ticket": {
        "id": 154565,
        "project": 13,
        "channelName": "Issue #052",
        "channelUrl": "sendbird_group_channel_3393523_a3e2ffdd3df691628450be705216a74048684ebd",
        "createdAt": "2021-02-18T01:00:18.638015Z",
        "closedAt": null,
        "issuedAt": "2021-02-18T01:00:20.272178Z",
        "durationTime": null,
        "pendingTime": 13,
        "conversationTime": null,
        "customer": {
            "id": 1647,
            "sendbirdId": "tree",
            "channelType": "QnA",
            "project": 13,
            "createdAt": "2020-01-02T06:47:22.146062Z",
            "displayName": "tree",
            "photoThumbnailUrl": ""
        "closeStatus": "NOT_CLOSED",
        "recentAssignment": {
            "id": 56505,
            "assignedTicket": 154565,
            "agent": {
                "id": 3129,
                "displayName": "cindybot",
                "project": 13,
                "user": null,
                "sendbirdId": "sendbird_desk_agent_id_cindy_c1254393-4d8c-446a-8797-16f4b1655045",
                "role": "AGENT",
                "createdAt": "2021-02-09T01:23:07.422203Z",
                "status": "ACTIVE",
                "connection": "OFFLINE",
                "email": "",
                "photoThumbnailUrl": "",
                "connectionUpdatedAt": null,
                "tier": "INTERMEDIATE"
            "assignedAt": "2021-02-18T01:00:33.488282Z",
            "responsedAt": null,    // This property will be deprecated soon. Use `respondedAt` instead.
            "respondedAt": null,
            "endedAt": null,
            "status": "NOT_RESPONDED",
            "unreadCount": 2,
            "responseTime": null
        "closeComment": null,
        "info": "{\"ticket\":{\"subject\":\"Issue #052\",\"requester\":{\"name\":\"tester\",\"email\":\"tester\"}}}",
        "messageCount": 2,
        "lastMessage": "Hi, can I reset my password?",
        "lastMessageSender": "CUSTOMER",
        "lastMessageAt": "2021-02-18T01:00:36.571000Z",
        "lastUserMessageSender": "CUSTOMER",
        "lastUserMessageAt": "2021-02-18T01:00:36.571000Z",
        "updatedAt": "2021-02-18T01:00:36.878782Z",
        "firstAssignmentToCloseTime": null,
        "firstResponseTime": null,
        "channelType": "QnA",
        "data": "",
        "lastSeenAt": 0,
        "group": {
            "id": 51,
            "name": "CS team",
            "key": null,
            "project": 13,
            "createdAt": "2019-12-30T04:57:58.743091Z",
            "createdBy": 27,
            "description": "Customer service team."
        "customFields": [],
        "tags": [],
        "customerSatisfactionScore": null,
        "customerSatisfactionComment": null,
        "priority": "URGENT",
        "priorityValue": 40,
        "status2": "ACTIVE",
        "relatedChannels": null,
        "lastAssignedAgent": 3129