Platform API
Desk Webhooks

Webhooks

With webhooks turned on in your Sendbird application, your server will receive HTTP POST requests from Sendbird server in the form of the response containing information on all events that occur within the application.

The webhooks can be useful when you build your own custom notification service, such as a SMS notification or an email system for your offline users.


Configuration

You can configure a webhook endpoint URL and other settings on the Settings > Desk > Webhooks in 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.

Light Color Skin
Copy
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.

Light Color Skin
Copy
# 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.

Webhook events

Ticket
EventTriggered when

TICKET.CREATED

A ticket is created.

TICKET.STATUS.UPDATED

The information of a ticket is updated. Currently, this webhook event is sent only when the customer satisfaction rating of the ticket is updated.

TICKET.CLOSED

A ticket is closed.

Agent's connection log
EventTriggered when

AGENT_CONNECTION_LOG.CREATED

A connection log is created due to a change of the connection status of an agent.


TICKET.CREATED

The following shows a webhook payload of a TICKET.CREATED event.

Light Color Skin
Copy
{
    "eventType": "TICKET.CREATED",
    "dataType": "TICKET",
    "createdAt": "2020-07-21T07:32:38.740534Z",
    "id": 97627,
    "project":{
        "id": 13,
        "pid": "47895be2-5a6b-4dc4-bc63-c26c4b3330db"
    },
    "data":{
        "id": 3351,
        "project": 13,
        "channelName": "Issue #818",
        "createdAt": "2020-07-21T07:32:38.669346Z",
        "channelUrl": "sendbird_group_channel_730883_973004c40cc0c881e603b61ba5dab3ce17a2a",
        "closedAt": null,
        "issuedAt": null,
        "durationTime": null,
        "pendingTime": 0,
        "conversationTime": 36838815,
        "customer": {
            "id": 680,
            "sendbirdId": "hi_duskan",
            "channelType": "SENDBIRD",
            "project": 13,
            "createdAt": "2020-03-12T05:25:35.055635Z",
            "memo": null,
            "displayName": "Duskan",
            "photoThumbnailUrl": "https://sendbird.com/main/img/profiles/profile_duskan.png",
            "customFields": []
        },
        "status": "INITIALIZED",             # will be deprecated soon and only status2 will be returned.
        "closeStatus": "NOT_CLOSED",
        "recentAssignment": {
            "id": 8177,
            "assignedTicket": 3351,
            "agent": {
                "id": 28,
                "displayName": "Angel_Mike",
                "project": 13,
                "user": 13,
                "sendbirdId": "sendbird_desk_agent_id_319bf388-3e97-4245-870e-2653f2e9ecb0",
                "role": "AGENT",
                "createdAt": "2020-07-12T05:30:35.504014Z",
                "status": "ACTIVE",
                "connection": "ONLINE",
                "email": "mike.angel@sendbird.com",
                "photoThumbnailUrl": "https://file.sendbird.com/profile_images/mike_vacation.png",
                "connectionUpdatedAt": "2020-08-13T04:31:28.653651Z",
                "tier": "EXPERT"
            },
            "assignedAt": "2020-07-21T06:52:55.993589Z",
            "responsedAt": "2020-07-21T06:53:02.526407Z",
            "endedAt": "2020-07-21T07:16:14.995469Z",
            "status": "IDLE",
            "unreadCount": 0,
            "responseTime": 5
        },
        "closeComment": null,
        "info": "{\"ticket\":{\"subject\":\"Issue #818\",\"requester\":{\"name\":\"Duskan\",\"email\":\"hi_duskan\"}}}",
        "messageCount": null,
        "lastMessage": null,
        "lastMessageSender": "PLATFORM",
        "lastMessageAt": null,
        "lastMessageMembers": "[]",
        "updatedAt": "2020-07-21T07:32:38.669388Z",
        "lastMessagePayload": null,
        "firstAssignmentToCloseTime":null 
        "isWip": false,
        "channelType": "SENDBIRD",
        "data": "{}",
        "lastSeenAt": 0,
        "group": {
            "id": 51,
            "name": "Sales",
            "key": null,
            "project": 13,
            "createdAt": "2019-06-20T04:57:58.743091Z",
            "createdBy": 27,
            "description": "Sales related tickets are assinged to this time."
        },
        "customFields": [],
        "customerSatisfactionScore": null,
        "customerSatisfactionComment": null,
        "priority": "URGENT",
        "priorityValue": 40,
        "status2": "INITIALIZED",
        "relatedChannels": null
    }
}

TICKET.STATUS.UPDATED

The following shows a webhook payload of a TICKET.STATUS.UPDATED event.

Light Color Skin
Copy
{
    "eventType": "TICKET.STATUS.UPDATED",
    "dataType": "TICKET",
    "createdAt": "2020-07-21T07:34:39.054563Z",
    "id": 97627,
    "project":{
        "id": 13,
        "pid": "47895be2-5a6b-4dc4-bc63-c26c4b3330db"
    },
    "data":{
        "id": 3351,
        "project": 13,
        "channelName": "Issue #818",
        "createdAt": "2020-07-21T07:32:38.669346Z",
        "channelUrl": "sendbird_group_channel_730883_973004c40cc0c881e603b61ba5dab3ce17a2a",
        "closedAt": null,
        "issuedAt": "2020-07-21T06:52:55.701744Z",
        "durationTime": 36898079,
        "pendingTime": 0,
        "conversationTime": 36838815,
        "customer": {
            "id": 680,
            "sendbirdId": "hi_duskan",
            "channelType": "SENDBIRD",
            "project": 13,
            "createdAt": "2020-03-12T05:25:35.055635Z",
            "memo": null,
            "displayName": "Duskan",
            "photoThumbnailUrl": "https://sendbird.com/main/img/profiles/profile_duskan.png",
            "customFields": []
        },
        "status": "ASSIGNED",             # will be deprecated soon and only status2 will be returned.
        "closeStatus": "NOT_CLOSED",
        "recentAssignment": {
            "id": 8177,
            "assignedTicket": 3351,
            "agent": {
                "id": 28,
                "displayName": "Angel_Mike",
                "project": 13,
                "user": 13,
                "sendbirdId": "sendbird_desk_agent_id_319bf388-3e97-4245-870e-2653f2e9ecb0",
                "role": "AGENT",
                "createdAt": "2020-03-12T05:30:35.504014Z",
                "status": "ACTIVE",
                "connection": "ONLINE",
                "email": "mike.angel@sendbird.com",
                "photoThumbnailUrl": "https://file.sendbird.com/profile_images/mike_vacation.png",
                "connectionUpdatedAt": "2020-08-13T04:31:28.653651Z",
                "tier": "EXPERT"
            },
            "assignedAt": "2020-07-21T06:52:55.993589Z",
            "responsedAt": "2020-07-21T06:53:02.526407Z",
            "endedAt": "2020-07-21T07:16:14.995469Z",
            "status": "IDLE",
            "unreadCount": 0,
            "responseTime": 5
        },
        "closeComment": null,
        "info": "{\"ticket\":{\"subject\":\"Issue #818\",\"requester\":{\"name\":\"Duskan\",\"email\":\"hi_duskan\"}}}",
        "messageCount": 1,
        "lastMessage": "Hi, what can I do for you?",
        "lastMessageSender": "AGENT",
        "lastMessageAt": "2020-07-21T07:32:40.278000Z",
        "lastMessageMembers": "[]",
        "updatedAt": "2020-07-21T07:32:40.447894Z",
        "lastMessagePayload": null,
        "firstAssignmentToCloseTime": null,
        "isWip": false,
        "channelType": "SENDBIRD",
        "data": "{}",
        "lastSeenAt": 0,
        "group": {
            "id": 51,
            "name": "Sales",
            "key": null,
            "project": 13,
            "createdAt": "2019-06-20T04:57:58.743091Z",
            "createdBy": 27,
            "description": "Sales related tickets are assinged to this time."
        },
        "customFields": [],
        "customerSatisfactionScore": null,
        "customerSatisfactionComment": null,
        "priority": "URGENT",
        "priorityValue": 40,
        "status2": "ACTIVE",
        "relatedChannels": null
    }
}

TICKET.CLOSED

The following shows a webhook payload of a TICKET.CLOSED event.

Light Color Skin
Copy
{
    "eventType": "TICKET.CLOSED",
    "dataType": "TICKET",
    "createdAt": "2020-07-21T07:38:00.350778Z",
    "id": 97627,
    "project":{
        "id": 13,
        "pid": "47895be2-5a6b-4dc4-bc63-c26c4b3330db"
    },
    "data":{
        "id": 3351,
        "project": 13,
        "channelName": "Issue #818",
        "createdAt": "2020-07-21T07:32:38.669346Z",
        "channelUrl": "sendbird_group_channel_730883_973004c40cc0c881e603b61ba5dab3ce17a2a",
        "closedAt": "2020-07-21T07:37:59.940971Z",
        "issuedAt": "2020-07-21T06:52:55.701744Z",
        "durationTime": 36898079,
        "pendingTime": 0,
        "conversationTime": 36838815,
        "customer": {
            "id": 680,
            "sendbirdId": "hi_duskan",
            "channelType": "SENDBIRD",
            "project": 13,
            "createdAt": "2020-03-12T05:25:35.055635Z",
            "memo": null,
            "displayName": "Duskan",
            "photoThumbnailUrl": "https://sendbird.com/main/img/profiles/profile_duskan.png",
            "customFields": []
        },
        "status": "CLOSED",             # will be deprecated soon and only status2 will be returned.
        "closeStatus": "CLOSED_BY_AGENT",
        "recentAssignment": {
            "id": 8177,
            "assignedTicket": 3351,
            "agent": {
                "id": 28,
                "displayName": "Angel_Mike",
                "project": 13,
                "user": 13,
                "sendbirdId": "sendbird_desk_agent_id_319bf388-3e97-4245-870e-2653f2e9ecb0",
                "role": "AGENT",
                "createdAt": "2020-03-12T05:30:35.504014Z",
                "status": "ACTIVE",
                "connection": "ONLINE",
                "email": "mike.angel@sendbird.com",
                "photoThumbnailUrl": "https://file.sendbird.com/profile_images/mike_vacation.png",
                "connectionUpdatedAt": "2020-08-13T04:31:28.653651Z",
                "tier": "EXPERT"
            },
            "assignedAt": "2020-07-21T06:52:55.993589Z",
            "responsedAt": "2020-07-21T06:53:02.526407Z",
            "endedAt": "2020-07-21T07:16:14.995469Z",
            "status": "IDLE",
            "unreadCount": 0,
            "responseTime": 5
        },
        "closeComment": "",
        "info": "{\"ticket\":{\"subject\":\"Issue #818\",\"requester\":{\"name\":\"Duskan\",\"email\":\"hi_duskan\"}}}",
        "messageCount": 6,
        "lastMessage": "This ticket is assigned to Summer by the system.",
        "lastMessageSender": "PLATFORM",
        "lastMessageAt": "2020-07-21T07:34:39.261000Z",
        "lastMessageMembers": "[]",
        "updatedAt": "2020-07-21T07:34:39.381004Z",
        "lastMessagePayload": null,
        "firstAssignmentToCloseTime": 201,
        "isWip": false,
        "channelType": "SENDBIRD",
        "data": "{}",
        "lastSeenAt": 0,
        "group": {
            "id": 51,
            "name": "Sales",
            "key": null,
            "project": 13,
            "createdAt": "2019-06-20T04:57:58.743091Z",
            "createdBy": 27,
            "description": "Sales related tickets are assinged to this time."
        },
        "customFields": [],
        "customerSatisfactionScore": null,
        "customerSatisfactionComment": null,
        "priority": "URGENT",
        "priorityValue": 40,
        "status2": "CLOSED",
        "relatedChannels": null
    }
}

AGENT_CONNECTION_LOG.CREATED

The following shows a webhook payload of a AGENT_CONNECTION_LOG.CREATED event.

Light Color Skin
Copy
{
    "eventType": "AGENT_CONNECTION_LOG.CREATED",
    "dataType": "AGENT_CONNECTION_LOG",
    "createdAt": "2020-07-21T07:44:01.288198Z",
    "id": 97652,
    "project": {
        "id": 13,
        "pid": "47895be2-5a6b-4dc4-bc63-c26c4b3330db"
    },
    "data": {
        "id": 1641,
        "agent": 107,
        "fromConnection": "ONLINE",
        "toConnection": "OFFLINE",
        "durationTime": null,
        "createdAt": "2020-07-21T07:44:01.243390Z",
        "createdBy": 107
    }
}