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.

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

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.

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

content-type: application/json
...

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

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

The following table lists the parameters that this action supports.

?display_all_webhook_categories=true

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

{
    "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"
        ]
    }
}

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.

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

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

# Request body example
{
    "enabled": true,
    "url": "https://example.com/calls/notifications",
    "enabled_events": ["*"]
}

# Request body example
{
    "enabled": true,
    "url": "https://example.com/calls/notifications",
    "enabled_events": [
        "direct_call:dial",
        "direct_call:end"
    ]
}

# Request body example
{
    "enabled": false,
    "enabled_events": []
}

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

{
    "enabled": true,
    "url": "https://example.com/calls/notifications",
    "enabled_events": [
        "direct_call:dial",
        "direct_call:accept",
        "direct_call:end"
    ]
}

{
    "enabled": true,
    "url": "https://example.com/calls/notifications",
    "enabled_events": [
        "direct_call:dial",
        "direct_call:end"
    ]
}

{
    "enabled": false,
    "url": "https://example.com/calls/notifications",
    "enabled_events": []
}

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

{
    "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"
}

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

{
    "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"
}

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

{
    "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"
}