Chat / Platform API
Current version: v3
    Chat Platform API v3
    Chat Platform API
    Chat
    Platform API
    Home
    /
    Chat
    /
    Platform API

    Overview

    With webhooks turned on in your Sendbird application, your server receives HTTP POST requests from 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 the 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 and keep-alive.
    • The endpoint needs to respond to POST requests.
    • The endpoint needs to parse JSON payloads.

    By default, 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 Sendbird server include the following headers.

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

    To verify the request on your server side, create a comparison value exactly the same way as 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 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.


    Webhook events

    List of open channel events

    EventInvoked when

    open_channel:create

    An open channel is created.

    open_channel:remove

    An open channel is removed.

    open_channel:enter

    A user enters an open channel.

    open_channel:exit

    A user exits an open channel.

    open_channel:message_send

    A message is sent within an open channel.

    open_channel:message_update

    A message is updated in an open channel.

    open_channel:message_delete

    A message is deleted from an open channel.

    List of group channel events

    EventInvoked when

    group_channel:create

    A group channel is created.

    group_channel:changed

    A group channel information is changed.

    group_channel:remove

    A group channel is removed.

    group_channel:invite

    A user invites another user.

    group_channel:decline_invite

    A user declines an invitation.

    group_channel:join

    A user joins a group channel.

    group_channel:leave

    A user leaves a group channel.

    group_channel:message_send

    A message is sent within a group channel.

    group_channel:message_read

    A user has no more unread messages in a group channel.

    group_channel:message_update

    A message is updated in a group channel.

    group_channel:message_delete

    A message is deleted from a group channel.

    group_channel:freeze_unfreeze

    A group channel is either frozen or unfrozen.

    group_channel:reaction_add

    A user adds reactions to a message.

    group_channel:reaction_delete

    A user deletes reactions from a message.

    List of user events

    EventInvoked when

    user:block

    A user blocks another user.

    user:unblock

    A user unblocks another user.

    List of operator events

    EventInvoked when

    operators:register_by_operator

    One or more operators are registered by another operator's client app.

    operators:unregister_by_operator

    The registration of one or more operators is canceled by another operator's client app.

    List of report events

    EventInvoked when

    message:report

    A message is reported by a user.

    user:report

    A user is reported by another user.

    open_channel:report

    An open channel is reported by a user.

    group_channel:report

    A group channel is reported by a user.

    List of alert events

    EventInvoked when

    alert:user_message_rate_limit_exceeded

    A user exceeds the allowed number of messages to send.

    List of profanity filter events

    EventInvoked when

    profanity_filter:replace

    Explicit words in a message are replaced with asterisks (*).

    profanity_filter:block

    A message with explicit words is blocked.

    profanity_filter:moderate

    A user is imposed with one of the moderation penalties among mute, kick, and ban.

    List of image moderation events

    EventInvoked when

    image_moderation:block

    A message with explicit images or inappropriate image URLs is blocked.

    List of announcement events

    EventInvoked when

    announcement:create_channels

    Channels are created for sending an announcement to target users who do not already have a channel with the announcement sender.

    announcement:send_messages

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