Webhooks

Webhook can notify teams when notifications are being sent. 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.

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

To view the image in full screen, click on the

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 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.

# 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.

The following is the payload sample for notifications:

{
  "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, 
}