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.
Webhook endpoint requirements
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
- The endpoint needs to respond to
- The endpoint needs to parse
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.
POST requests from the Sendbird server include the following headers.
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
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.
x-signaturerequest 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-signaturegenerated from the Sendbird server are always different. For this reason,
x-signaturecould be deprecated in the near future. Therefore, we recommend that you use
List of open channel events
An open channel is created.
An open channel is removed.
A user enters an open channel.
A user exits an open channel.
A message is sent within an open channel.
A message is updated in an open channel.
A message is deleted from an open channel.
List of group channel events
A group channel is created.
A group channel information is changed.
A group channel is removed.
A user invites another user.
A user declines an invitation.
A user joins a group channel.
A user leaves a group channel.
A message is sent within a group channel.
A user has no more unread messages in a group channel.
A message is updated in a group channel.
A message is deleted from a group channel.
A group channel is either frozen or unfrozen.
A user adds reactions to a message.
A user deletes reactions from a message.
List of user events
A user blocks another user.
A user unblocks another user.
List of operator events
One or more operators are registered by another operator's client app.
The registration of one or more operators is canceled by another operator's client app.
List of report events
A message is reported by a user.
A user is reported by another user.
An open channel is reported by a user.
A group channel is reported by a user.
List of alert events
A user exceeds the allowed number of messages to send.
List of profanity filter events
Explicit words in a message are replaced with asterisks (*).
A message with explicit words is blocked.
A user is imposed with one of the moderation penalties among mute, kick, and ban.
List of image moderation events
A message with explicit images or inappropriate image URLs is blocked.
List of announcement events
Channels are created for sending an announcement to target users who do not already have a channel with the announcement sender.
An announcement message is sent to target channels and users.
Notice that the
unread_message_count property of a webhook payload is changed as follows:
unread_message_countproperty is deprecated.
total_unread_message_countproperty replaces the
channel_unread_message_countproperty represents the number of unread messages in a current channel.
Note: To learn more about how to use webhooks, see this tutorial.