Webhooks for Bots

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.

Configuration

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

Webhook endpoint requirements

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.

Headers

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

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

x-hub-signature

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=' + hmac.new(secret_key, 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

All webhook events depend on the following data structure.

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

List of properties

Property name	Type	Description
eventType	string	The type of the event.
botWebhookEvent	nested object	An object that contains information about the bot and the chat message from a customer.
ticket	nested object	An object that contains information about the ticket.

Webhook events

Ticket

Event	Triggered when
MESSAGE.RECEIVED	A bot receives the message sent by a customer.

MESSAGE.RECEIVED

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

{
    "eventType": "MESSAGE.RECEIVED",
    "botWebhookEvent": {
        "id": 115,
        "bot": 63,
        "status": "SENT",
        "webhookUrl": "https://welcometo.sendbird.com/",
        "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": "https://welcome.sendbird.com/sample/profiles/happy_tree.png"
        },
        "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
    }
}

On this page

Configuration Webhook endpoint requirements Headers

x-hub-signature

Data structure Webhook events MESSAGE.RECEIVED