How to use webhooks to build real-time features and link API services

With SendBird’s chat framework, you can easily design, build, and customize the perfect chat or messaging solution for your app. It’s secure, reliable, and seamless — and it’s developer-friendly thanks to the Platform API and other developer resources.

To harness responsive real-time features and other API services used by your application, you first need to enable webhooks. In this article, you’ll find everything you need to know about webhooks, including how to use them to customize responsive features in your app with SendBird.

What is a webhook?

A webhook creates an HTTP callback to one server with data about an event that occurs in another web service in real time. Compared to polling, webhooks are far more efficient and enable you to build features that reflect virtually real time data. It is the best way for developers to create an action on one web service according to events that happen on another web service.

How webhooks support custom real-time features and link API services

Webhooks are invaluable when you’d like to trigger behavior in one server according to the behavior of another — in other words, when you want to link functions between different API services or create features that respond to user actions. Often, developers will use webhooks to create a customized notification system for events that occur in a SendBird-enabled app.

Here’s an example. You’d like to send a notification to members of a channel when someone sends a message within it. A webhook will let your servers know when a message is sent to the channel by sending an HTTP POST with specific data about the message and channel. If the user who receives the message is logged into your app, you can now trigger a push notification to alert them of the message. If the recipient isn’t logged into the app and cannot receive a push, then you can use webhooks to trigger an SMS to a phone number, email address, or both.

This is both a common example and, perhaps, the most important because many apps across different industries need to keep users notified of new messages. Use cases include:

• In a healthcare app, when a doctor, patient, or healthcare concierge receives a time-sensitive message.
• In an on-demand app, when a user needs to receive information and updates about their service’s status. This is especially important because being timely is so crucial for on-demand apps.
• In a dating app, when you want to draw users back to the app to see any outstanding matches or messages.
• In a marketplace, when a user expresses interest in another user’s product and the seller wants to be notified so they can reach the buyer when his/her intent is highest.
• In a gaming app, when a user sends a reminder about a raid, guild or game event to a channel that he/she doesn’t want members to miss

While webhooks are often used for custom notification services, there are many more ways to use them to enhance the user experience of your app. Other uses for webhooks include triggering a payments API, triggering a social media API, and more.

Using webhooks with SendBird

Used in SendBird, webhooks send an HTTP POST request with a JSON payload to your server when any event occurs on the SendBird servers, such as:

• A user ‘sends’, ‘deletes’, or ‘reads’ a message in a channel
• A user ‘creates’ or ‘leaves’ a channel, or ‘invites’ another user to a channel
• A user ‘blocks’ or ‘unblocks’ another user

Read the full list of events supported by SendBird webhooks at our Platform API documentation.

How to enable webhooks for different events

By enabling webhooks for specific events, you can control the number and type of HTTP requests you receive.

To enable webhooks, make the following HTTP request

PUT https://api-{application_id}.sendbird.com/v3/applications/settings/webhook

The request body only supports the property, enabled_events[], described below.

The following example of a Request body shows a user turning on webhooks for ‘creating’ and ‘joining’ a channel (group_channel:create and group_channel:join), and ‘inviting’ a user to a channel (group_channel:invite).

If successful, this request returns information about the webhook configuration in the response body as follows.

To retrieve a list of your currently enabled webhooks, use the following request:

GET https://api-{application_id}.sendbird.com/v3/applications/settings/webhook

Authenticating webhooks from SendBird

Verifying that an unaltered webhook request comes from SendBird is crucial to maintaining security. For that reason, SendBird produces a signature in SHA-256 and applies it to both the POST request body and your access token.

Each HTTP POST request from SendBird will include the following header:

The x-signature is an important feature ensuring that the HTTP POST request you receive is

1. From SendBird
2. Not altered by a third-party

The value of the x-signature is generated by applying SHA-256 to the POST request body and your API token. To verify the request, apply SHA-256 to the request body and your API token. Next, verify that the resulting value is equal to the x-signature.

Example Code:

SendBird’s webhook behavior

Occasionally, a server does not successfully receive a request. If a webhook request fails, you can expect the following behavior from SendBird’s webhooks.

• Timeout per request: 5 seconds
• If a timeout occurs, SendBird retries the request to your server 3 times
• If your server can’t receive the request 3 times in 15 seconds, it will not receive the request

To avoid too many requests, you should implement your endpoint to respond immediately to the server with a 200 OK response.

Setting up your webhook architecture

To be able to support heavy traffic to your servers (including webhook requests), we recommend setting up your architecture in a way similar to this diagram. In this example diagram, we leverage the AWS tech stack (for example, API Gateway) to create a highly scalable architecture.

Ensure your webhook endpoint meets these requirements

When specific events occur in your SendBird application, SendBird sends HTTP POST requests with JSON payloads to your webhook endpoint. Your webhook endpoint must meet the following requirements:

• The endpoint must support HTTP/1.1 and keep-alive.
• The endpoint must respond to POST requests.
• The endpoint must parse JSON payloads.

Example webhook request from SendBird when a user ‘sends’ a message

The following is an example of a webhook request sent to your server. When a user sends a message, SendBird’s webhooks will send this request. Once you receive the request, you can use the JSON payload to implement behavior in other servers whenever a message is sent in the SendBird client.

Request Header

Request Body

Webhooks: How to get the most from your API service

Thanks to the flexibility and power of webhooks, developers can implement new custom features within their apps and link SendBird’s Platform API to a multitude of other API services.

Ultimately, webhooks make it possible to link all the API services your business uses to create some really incredible experiences for your users. We hope you’ll continue to explore how you can use webhooks to introduce features that your users will love, and the SendBird team is always here to help.