Platform API
Calls Webhooks

Webhooks

With webhooks turned on in your Sendbird application, your server will receive HTTP POST requests from Sendbird server in the form of the response containing information on all events that occur within the application.

The webhooks can be useful when you build your own custom notification service, such as notifying call statuses for your offline users.


Configuration

You can configure a webhook endpoint URL and other settings on the Settings > Calls > Webhooks in your dashboard.


Webhook endpoint requirements

HTTP POST requests with JSON payloads are sent to your webhook endpoint upon specific events in your Sendbird application.

  • 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 1 second. The server sends the same POST request up to three times until it receives a response. To avoid too many requests, you should implement the endpoint to respond immediately to the server with a 200 OK response.

Note: When you need a process or function which handles webhook payloads, it should be implemented to be executed asynchronously from that of which responds to the server. If they are executed synchronously, it can cause the endpoint to stop working properly when many events happen on your application.


Headers

HTTP POST requests from Sendbird server will include the following headers.

Light Color Skin
Copy
content-type: application/json
...

Webhook events

Direct call
EventTriggered when

direct_call:dial

A direct call's signal is forwarded to callee.

direct_call:accept

A direct call is accepted by the callee.

direct_call:end

A direct call is ended by either the caller or callee.


Retrieve a list of subscribed events

Retrieves a list of events for your webhook server to receive payloads for.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.calls.sendbird.com/v1/applications/{application_id}/settings/webhook

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

application_id

string

Specifies the unique ID of the application.

OptionalTypeDescription

display_all_webhook_categories

boolean

Determines whether to include a list of all supported webhook events as the all_webhook_categories property in the response. (Default: false)

Query string example
Light Color Skin
Copy
?display_all_webhook_categories=true

Response

If successful, this action returns the information about the webhook configuration in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "webhook":  {
        "enabled": true,
        "url": "https://example.com/calls/notifications",
        "enabled_events": [
            "direct_call:dial"
        ],
        "all_webhook_categories": [
            "direct_call:dial",
            "direct_call:accept",
            "direct_call:end"
        ]
    }
}

Choose which events to subscribe to

hooses which events for your webhook server to receive payloads for. By subscribing to specific events based on your own needs, you can control the number of HTTP requests to your webhook server.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.calls.sendbird.com/v1/applications/{application_id}/settings/webhook

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

application_id

string

Specifies the unique ID of the application.

OptionalTypeDescription

enabled

boolean

Determines whether webhooks are turned on in your Sendbird application or not. (Default: false)

url

string

Specifies the URL of your webhook server to receive payloads for events.

include_members

boolean

Determines whether to include the information on the members of group channels in payloads. (Default: false)

enabled_events[]

array

Specifies an array of one or more events for your webhook server to subscribe to. If set to an asterisk (*) only, the server will subscribe to all supported events. If set to an empty array, the server will unsubscribe from all (which indicates turning off webhooks).

subscribe all
subscribe selected
unsubscribe all
Light Color Skin
Copy
# Request body example
{
    "enabled": true,
    "url": "https://example.com/calls/notifications",
    "enabled_events": ["*"]
}
Light Color Skin
Copy
# Request body example
{
    "enabled": true,
    "url": "https://example.com/calls/notifications",
    "enabled_events": [
        "direct_call:dial",
        "direct_call:end"
    ]
}
Light Color Skin
Copy
# Request body example
{
    "enabled": false,
    "enabled_events": []
}

Response

If successful, this action returns the information about the webhook configuration in the response body.

subscribe all
subscribe selected
unsubscribe all
Light Color Skin
Copy
{
    "enabled": true,
    "url": "https://example.com/calls/notifications",
    "enabled_events": [
        "direct_call:dial",
        "direct_call:accept",
        "direct_call:end"
    ]
}
Light Color Skin
Copy
{
    "enabled": true,
    "url": "https://example.com/calls/notifications",
    "enabled_events": [
        "direct_call:dial",
        "direct_call:end"
    ]
}
Light Color Skin
Copy
{
    "enabled": false,
    "url": "https://example.com/calls/notifications",
    "enabled_events": []
}

direct_call:dial

The following shows a webhook payload of a direct_call:dial event.

Light Color Skin
Copy
{
    "category": "direct_call:dial",
    "occurred_at": 1590570513368,
    "direct_call": {
        "call_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "caller_id": "user-917b11f6b56e41d2aee535bc4ba143c2-1590570511",
        "callee_id": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511"
    },
    "sendbird_call": {
        "version": 1,
        "message_id": "6ac84681-4e18-4982-9090-d6f847b6cfe3",
        "cmd": "CALL",
        "type": "dial",
        "payload": {
            ...

        }
    },
    "application_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

direct_call:accept

The following shows a webhook payload of a direct_call:accept event.

Light Color Skin
Copy
{
    "category": "direct_call:accept",
    "occurred_at": 1590570514274,
    "direct_call": {
        "call_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "caller_id": "user-917b11f6b56e41d2aee535bc4ba143c2-1590570511",
        "callee_id": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511"
    },
    "application_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

direct_call:end

The following shows a webhook payload of a direct_call:end event.

Light Color Skin
Copy
{
    "category": "direct_call:end",
    "occurred_at": 1590570514415,
    "result": "completed",
    "direct_call": {
        "call_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "caller_id": "user-917b11f6b56e41d2aee535bc4ba143c2-1590570511",
        "callee_id": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511"
    },
    "application_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}