Webhooks

Webhooks can notify teams when a certain event takes place in regard to templates and notifications. Set Notification webhooks on Sendbird Dashboard for your server to receive HTTP POST requests from the Sendbird server in JSON format, which contain information on all events within your Sendbird application.

Set up webhooks

To listen to events, set up webhooks on the dashboard first as follows:

Log in the Sendbird Dashboard.
Navigate to Settings > Business Messaging > Webhooks and turn on the feature.
Enter the webhook URL for the Sendbird server to send a request and choose the events you wish to subscribe to.

Settings	Description
URL	Specifies the URL that Sendbird can send the the payload to.
Events	Selects webhook events to listen to. Refer to the table below for the supported events.

List of webhook events

The following table lists the webhook events that you can subscribe to.

Event	Description
notification:send_realtime	Notifies you when a request is made for a real-time notification.
notification:send_batch	Notifies you when a request is made for a batch notification.
notification:template_create	Notifies you when a template is created.
notification:template_archive	Notifies you when a template is archived.
notification:template_unarchive	Notifies you when a template is unarchived.
notification:template_edit	Notifies you when a template is edited.
notification:template_approval_update	Notifies you when the approval status of a channel’s template has changed.

Note: See the Payload section below for more information on the payload format.

Authentication headers

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

user-agent: SendBird
content-type: application/json
x-sendbird-signature: {x_sendbird_signature}

Note: Upon selection, the Sendbird server will dispatch webhook events in JSON format to your specified server. This occurs whenever a real-time or batch notification is triggered. Including template variables can be enabled by request, allowing all webhooks to include these variables, as detailed in the payload format below.

x-sendbird-signature

x-sendbird-signature is used as a request header to ensure that the source of the request comes from the 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 x-sendbird-signature is generated through the SHA-256 encryption on the the Sendbird server side.

To verify the request on your server side, create a comparison value exactly the same way as the Sendbird server does, and then check if the result is equal to the value of the x-sendbird-signature.

Note: Always use the master API token to generate and validate the signature because secondary API tokens won't work. You can find the master API token on the dashboard.

PythonJavaScript

# Python sample: how to check the 'x-sendbird-signature' header value.

from __future__ import unicode_literals
import hashlib, hmac

api_token = b'YOUR_API_TOKEN'   # Convert a string of your API token to a bytes object.
webhook_payload = '{"category": "group_channel:message_send","sender": {"user_id": "Jeff","nickname": "Oldies but goodies",...},...}'  # The webhook payload parsed from an HTTP POST request you received.

signature_to_compare = hmac.new(
    key=api_token,
    msg=bytes(webhook_payload.encode('utf8')),
    digestmod=hashlib.sha256).hexdigest()

assert signature_to_compare == 'x_sendbird_signature'   # Check if the value of the 'x-sendbird-signature' request header matches the comparison value you created.

Note: The x-signature request header can be used for verification. However, when the request body contains non-ASCII characters such as emojis, the encrypted value on your server side and the value of x-signature generated from the Sendbird server are always different. For this reason, x-signature could be deprecated in the near future. Therefore, we recommend that you use x-sendbird-signature instead.

Payload

The following is the payload sample for notifications and templates:

Notifications

RealtimeBatch

{
  "category": "notification:send_realtime",
  "app_id": str, 
  "notification_message_id": str,
  "targets": list[str],
  "template_key": str, 
  "template.variables": dict[str, dict[str, Any]] -> user_id to variables, 
  "channel_key": str, 
  "channel_url": str, 
}

Templates

CreatedArchivedUnarchivedEditedApproval status updated

{
  "category": "notification:template_create",
  "template": {
    "key": "payload-test",
    "name": "payload-test",
    "created_at": 1726734831843,
    "updated_at": 1726734831843,
    "is_archived": false,
    "version: 2,
    "sequence": {
        "steps": [
            {
                "channels": [
                    {
                        "key": "data",
                        "type": "feed"
                    },
                    {
                        "key": "push",
                        "type": "push"
                    }
                ]
            },
            {
                "channels": [
                    {
                        "key": "kakao",
                        "type": "alimtalk"
                    }
                ]
            },
            {
                "channels": [
                    {
                        "key": "sms-korea",
                        "type": "sms"
                    }
                ]
            }
        ]
    },
    "variable_schema": [
        {
            "key": "booking_number",
            "type": "string",
            "name": "booking_number01"
        },
        {
            "key": "booking_date",
            "type": "string",
            "name": ""
        }
    ],
    "channels": [
        {
            "key": "data",
            "type": "feed",
            "data_type": "data_template",
            "message_retention_hours": 4320,
            "categories": [
                {
                    "name": "All"
                }
            ],
            "is_category_filter_enabled": false,
            "is_template_label_enabled": true,
            "data_template": [
                {
                    "key": "key",
                    "value": "value"
                }
            ],
            "ui_template": {}
        },
        {
            "key": "push",
            "type": "push",
            "content": {
                "title": "title",
                "body": "body",
                "data": {}
            }
        },
        {
            "key": "kakao",
            "type": "alimtalk",
            "content": {
                "templateContent": "Payment completed",
                "templateMessageType": "BA",
                "templateEmphasizeType": "NONE",
                "templateTitle": null,
                "templateSubtitle": null,
                "templateHeader": null,
                "templateItem": null,
                "templateItemHighlight": null,
                "templateImageName": null,
                "templateImageUrl": null,
                "buttons": null
            },
            "approval_status": "approved
        },
        {
            "key": "sms-korea",
            "type": "sms",
            "category": "SMS",
            "content": {
                "title": "",
                "body": "test body"
            }
        }
    ]
}

On this page

Set up webhooks

List of webhook events

Authentication headers

x-sendbird-signature

Payload

Notifications Templates