Overview

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

Webhooks are useful for building your own custom notification service, such as an SMS or email notification system, for your offline users.

Note: You can configure a webhook endpoint URL and other settings by going to Settings > Chat > Webhooks on Sendbird Dashboard.

HTTP POST requests with JSON payloads are sent to your webhook endpoint upon specific events on your Sendbird application. The endpoint should meet the following requirements:

• 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, the Sendbird server sends an HTTP POST request and waits for a response from your webhook endpoint for five seconds. The server sends the same POST request up to three times until it receives a response. To avoid too many requests, you should set up the endpoint to respond immediately to the server with a 200 OK response.

Note: Synchronous execution can cause the endpoint to stop working properly when too many events happen on your application. Therefore, the process that handles webhook payloads should be executed asynchronously from the one that responds to the server.

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

user-agent: SendBird
content-type: application/json
x-sendbird-signature: {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.

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

Notice that the unread_message_count property of a webhook payload is changed as follows:

• The unread_message_count property is deprecated.
• The total_unread_message_count property replaces the unread_message_count property.
• The channel_unread_message_count property represents the number of unread messages in a current channel.

Note: To learn more about how to use webhooks, see this tutorial.