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.

Data structure

All webhook events depend on the following data structure.

Light Color Skin
Copy
{
    "eventType": (String),
    "dataType": (String),
    "createdAt": (DateTime),
    "createdBy": (String)
    "id": (Number),
    "project":{
        "id": (Number),
        "pid": (String)
    },
    "data": (Object)
}
PropertyTypeDescription

id

int

The unique ID of the webhook.

project

nested object

An object that contains information of the project.

project.id

int

The unique ID of the project which consists of integers.

project.pid

string

The unique ID of the project which consists of random characters.

eventType

string

The type of the event.

data

nested object

An object that contains information about the webhook.

dataType

string

The type of the data. Valid values are TICKET or AGENT_CONNECTION_LOG.

createdAt

datetime

The date and time when the webhook was created, in ISO 8601 format.

createdBy

String

The subject who created the webhook. Valid values are:
- agent_{agent_id}: Indicates that the webhook is created by an agent whose ID is identical to the value of the agent_id.
- customer_{customer_id}: Indicates that the webhook is created by a customer whose ID is identical to the value of customer_id.
- system: Indicates that the webhook is created by Sendbird server.
- token_{masked_token}: Indicates that the webhook is created by Desk Platform API. The masked_token only shows the first 5 characters while remaining is replaced with asterisk (*) symbols.


Webhook events

Ticket
EventTriggered when

TICKET.CREATED

A ticket is created.

TICKET.STATUS.UPDATED

The status of a ticket is updated.

TICKET.CLOSED

A ticket is closed.

TICKET.UPDATED

The information of a ticket is updated. This webhook is sent only when the customer satisfaction rating of the ticket is updated.

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",
    "createdBy": "customer_1352",
    "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": []
        },
        "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 
        "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",
    "createdBy": "system",
    "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": []
        },
        "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,
        "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",
    "createdBy": "agent_1",
    "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": []
        },
        "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,
        "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
    }
}

TICKET.UPDATED

The following shows a webhook payload of a TICKET.UPDATED event. This event is sent only when the customer satisfaction rating of the ticket is updated.

Light Color Skin
Copy
{
    "eventType": "TICKET.UPDATED",
    "dataType": "TICKET",
    "createdAt": "2020-07-21T07:32:38.669346Z",
    "createdBy": "createdBy":"customer_1352", 
    "id":97651,
    "project": {
        "id": 23,
        "pid": "47895be2-5a6b-4dc4-bc63-c26c4b3330db"
    },
    "data":{
        "id": 9216,
        "project": 23,
        "channelName": "Issue #965",
        "createdAt": "2020-07-21T07:32:38.669346Z",
        "channelUrl": "sendbird_group_channel_7444658_3ac1def0229e9a0806ce68a4ccc48f2b589dec89",
        "closedAt": "2020-07-21T07:41:41.977985Z",
        "issuedAt": "2020-07-21T07:32:40.456084Z",
        "durationTime": 541,
        "customer": {
            "id": 1352,
            "sendbirdId": "tester",
            "project": 23,
            "createdAt": "2019-12-30T01:36:40.711650Z",
            "memo": null,
            "displayName": "tester",
            "channelType": "SENDBIRD",
            "photoThumbnailUrl": "https://static.sendbird.com/sample/profiles/profile_15_512px.png",
            "customFields": [
                {
                    "id": 240,
                    "key": "customer-string",
                    "value": ""
                }
            ]
    },
    "closeStatus": "CLOSED_BY_CUSTOMER",
    "recentAssignment": {
        "id": 8990,
        "assignedTicket": 9216,
        "agent": {
            "id":107,
            "displayName": "e2e-desk-agent-b2",
            "project": 23,
            "user": 28,
            "sendbirdId": "sendbird_desk_agent_id_5b34cb6f-8990-4556-987a-128c9eb70f9d",
            "role": "AGENT",
            "createdAt": "2020-01-27T14:18:14.922071Z",
            "status": "ACTIVE",
            "connection": "ONLINE",
            "email": "e2e-desk-agent-b2@sendbird.com",
            "photoThumbnailUrl": "",
            "connectionUpdatedAt": "2020-07-21T07:34:35.719899Z",
            "connectionUpdatedTs": 1595316875.719899,
            "groups": [
                {
                    "name": "Default team",
                    "key": null,
                    "id": 61
                },
                {
                    "name": "Team B",
                    "key": "teamb",
                    "id": j71
                }
            ],
            "tier":"INTERMEDIATE"
        },
        "assignedAt": "2020-07-21T07:41:13.653862Z",
        "responsedAt": null,
        "endedAt": "2020-07-21T07:41:41.977985Z",
        "status": "NOT_RESPONSED",
        "unreadCount": 0,
        "responseTime": null
        },
    "closeComment": "Automatically closed after `End of chat confirmed`.",
    "info": "{\"ticket\":{\"subject\":\"Issue #965\",\"requester\":{\"name\":\"tester\",\"email\":\"tester\"}}}",
    "messageCount": 10,
    "lastMessage": "How was your experience with us?",
    "lastMessageSender": "AGENT",
    "lastMessageAt": "2020-07-21T07:41:42.513000Z",
    "lastMessageMembers": "[]",
    "updatedAt": "2020-07-21T07:41:42.764046Z",
    "lastMessagePayload": null,
    "firstAssignmentToCloseTime": 423,
    "channelType": "SENDBIRD",
    "ticketType": "CUSTOMER_CHAT",
    "facebookPage": null,
    "twitterUser": null,
    "data": "{}",
    "lastSeenAt": 0,
    "group": {
        "id": 61,
        "name": "Default team",
        "key": null,
        "project": {...},
        "createdAt": "2019-12-30T04:57:58.855591Z",
        "createdBy": {
            "id": 92,
            "displayName": "e2e",
            "project": 23,
            "user": 12,
            "sendbirdId": "sendbird_desk_agent_id_087b4bef-123d-41aa-bb09-e78436d7dcb6",
            "role": "ADMIN",
            "createdAt": "2019-12-30T01:35:07.009898Z",
            "status": "ACTIVE",
            "connection": "OFFLINE",
            "email": "e2e@sendbird.com",
            "photoThumbnailUrl": "",
            "connectionUpdatedAt": null,
            "connectionUpdatedTs": null,
            "groups": [],
            "tier": "INTERMEDIATE"
        },
        "description": "Agents are added to this team as default. You can assign agents to other teams.",
        "memberCount": 6
    },
    "customFields": [],
    "customerSatisfactionScore": 5,
    "customerSatisfactionComment": "Great!",
    "priority": "MEDIUM",
    "priorityValue": 20,
    "instagramUser": null,
    "firstResponseTime": null,
    "status2": "CLOSED",
    "relatedChannels": null,
    "tags": []
}

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",
    "createdBy": "toekn_ab123***********",
    "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
    }
}