How to use webhooks to link API services with chat events

Introduction

With Sendbird Chat, you can easily design, build, and customize the perfect chat messaging solution for your app. It’s secure, reliable, and highly scalable—the Sendbird Platform API adds flexibility and functionalities on the server-side. It is very accessible, and there’s comprehensive documentation. To build responsive real-time features using other API services in your application, you first need to enable webhooks. In this article, you’ll find everything you need to know about webhooks, including how to build custom responses to chat events using Sendbird.

What is a webhook?

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

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

Often, developers will use webhooks to create a customized notification system for events 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, you can use webhooks to trigger an SMS to a phone number, email address, or both.

This is a common and essential example because many apps across different industries need to notify users of new messages. Use cases include:

• A doctor, patient, or healthcare concierge receives a time-sensitive message in a healthcare app.
• A user receives information and updates in an on-demand app.
• A user needs to see a new match or message in a dating app.
• A user expresses interest in a product, and the seller wants to receive a notification to reach out to the buyer in a marketplace.
• A user sends a reminder about a raid, guild, or game event to a channel in a gaming app.

Other uses for webhooks include triggering a payments API, triggering a social media or email API, and more.

Using webhooks with Sendbird

Used in Sendbird, webhooks send an HTTP POST request with a JSON payload to your server when an 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

Please read the complete list of events supported by the Sendbird webhooks in our Platform API documentation.

How to enable webhooks for different events

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

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 a critical feature ensuring that the HTTP POST request you receive is

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

The x-signature applies 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, confirm that the resulting value is equal to the x-signature.

Sendbird’s webhook behavior

Occasionally, a server does not 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 three times
• If your server can’t receive the request three 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 support heavy traffic to your servers (including webhook requests), we recommend setting up your architecture like in this diagram. We leverage the AWS tech stack (e.g., the 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.

Existing infrastructure security settings

In the case where you already have an infrastructure in place, and you will build a webhook receiving service within your existing infrastructure, consider how your current infrastructure’s security and setup settings may impact your ability to receive webhooks from Sendbird.

For example:

• A firewall could prevent calls from the Sendbird IP addresses.
• Cross-site scripting could detect a user-generated payload and block the Sendbird webhooks.
• Unwanted/unused webhooks with 400 errors that would not be flagged with a 200 response code.

Note, if a 400 error is returned, Sendbird will try to resend the notification automatically.

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

The following is an example of a webhook notification sent to your server. When a user sends a message, the Sendbird webhooks will send this notification. You can use the JSON payload to implement behaviors in other servers whenever a message is sent to the Sendbird client.

Conclusion

Thanks to the flexibility and power of webhooks, developers can implement new custom features within their apps and link the Sendbird Platform API to many other API services.

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