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.
Webhook endpoint requirements
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
andkeep-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.
Headers
HTTP POST
requests from the Sendbird server include the following headers.
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.
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 ofx-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 usex-sendbird-signature
instead.
Webhook events
List of open channel events
Event | Invoked when |
---|---|
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
Event | Invoked when |
---|---|
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
Event | Invoked when |
---|---|
A user blocks another user. | |
A user unblocks another user. |
List of operator events
Event | Invoked when |
---|---|
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
Event | Invoked when |
---|---|
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
Event | Invoked when |
---|---|
A user exceeds the allowed number of messages to send. |
List of profanity filter events
Event | Invoked when |
---|---|
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
Event | Invoked when |
---|---|
A message with explicit images or inappropriate image URLs is blocked. |
List of announcement events
Event | Invoked when |
---|---|
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:
- The
unread_message_count
property is deprecated. - The
total_unread_message_count
property replaces theunread_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.