Calls Platform API v1

Calls Platform API

Version 1

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.

content-type: application/json
...

Webhook events

Direct call

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

Group call

Event	Triggered when
room:create	A room is created.
room:delete	A room is deleted.
room:participant_enter	A participant entered a room.
room:participant_exit	A participant exited a room.
room:participant_disconnect	A participant is disconnected from a room.
room:invitation_send	An invitation is sent to a participant to join a room.
room:invitation_cancel	An invitation to join a room has been canceled.
room:invitation_accept	A participant has accepted an invitation to join a room.
room:invitation_decline	A participant has declined an invitation to join a room.
room:invitation_no_answer	A participant has neither accepted nor declined an invitation to join a room.

Retrieve a list of subscribed events

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

HTTP request

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

Required	Type	Description
application_id	string	Specifies the unique ID of the application.

Optional	Type	Description
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

?display_all_webhook_categories=true

Response

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

Status: 200 OK

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

Properties

Required	Type	Description
application_id	string	Specifies the unique ID of the application.

Optional	Type	Description
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 allsubscribe selectedunsubscribe all

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

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

subscribe allsubscribe selectedunsubscribe all

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

Direct call

There are three webhook events for direct call as shown below. To ensure your code remains error-free, note that new keys may be added to the webhook payload in the future.

direct_call:dial

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"
        "is_video": true,
        "custom_items": {
            "k1": "v1",
            "k2": "v2"
        }        
    },
    "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.

{
    "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"
        "is_video": true,
        "custom_items": {
            "k1": "v1",
            "k2": "v2"
        }        
    },
    "application_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

direct_call:end

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

{
    "category": "direct_call:end",
    "application_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "occurred_at": 1590570514415,
    "result": "completed",
    "direct_call": {
        "call_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "caller_id": "user-917b11f6b56e41d2aee535bc4ba143c2-1590570511",
        "callee_id": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511",
        "is_video": true,
        "custom_items": {
            "k1": "v1",
            "k2": "v2"
        },
        "created_at": 1590570400000,
        "started_at": 1590570500000,
        "ended_at": 1590570515000,
        "duration": 15000,
        "ended_by": "callee",
        "end_result": "completed"
    }
}

Note: The result property in the webhook payload is to be deprecated.

Group call

There are ten webhook events for group call as shown below. To ensure your code remains error-free, note that new keys may be added to the webhook payload in the future.

room:create

The following shows a webhook payload of a room:create event.

{
    "category": "room:create",
    "occurred_at": 1590570514274,
    "room": {
        "room_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "room_type": "small_room_for_video",
        "created_by": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511",
        "custom_items": {
            "call_quality": "HIGH"
        }
    },
    "application_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

room:delete

The following shows a webhook payload of a room:delete event.

{
    "category": "room:delete",
    "occurred_at": 1590570514274,
    "room": {
        "room_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "room_type": "small_room_for_video",
        "created_by": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511",
        "custom_items": {
            "call_quality": "HIGH"
        }
    },
    "application_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

room:participant_enter

The following shows a webhook payload of a room:participant_enter event.

{
    "category": "room:participant_enter",
    "occurred_at": 1590570514274,
    "room": {
        "room_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "room_type": "small_room_for_video",
        "created_by": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511",
        "custom_items": {
            "call_quality": "HIGH"
        }
    },
    "participant": {
        "user_id": "4d11f4fb-4808-4049-9bef-25e9cce7bfc4"
    },
    "application_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

room:participant_exit

The following shows a webhook payload of a room:participant_exit event.

{
    "category": "room:participant_exit",
    "occurred_at": 1590570514274,
    "room": {
        "room_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "room_type": "small_room_for_video",
        "created_by": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511",
        "custom_items": {
            "call_quality": "HIGH"
        }
    },
    "participant": {
        "user_id": "4d11f4fb-4808-4049-9bef-25e9cce7bfc4"
    },
    "application_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

room:participant_disconnect

The following shows a webhook payload of a room:participant_disconnect event.

{
    "category": "room:participant_disconnect",
    "occurred_at": 1590570514274,
    "room": {
        "room_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "room_type": "small_room_for_video",
        "created_by": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511",
        "custom_items": {
            "call_quality": "HIGH"
        }
    },
    "participant": {
        "user_id": "4d11f4fb-4808-4049-9bef-25e9cce7bfc4"
    },
    "application_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

room:invitation_send

The following shows a webhook payload of a room:invitation_send event.

{
    "category": "room:invitation_send",
    "occurred_at": 0,
    "application_id": "",
    "room": {
        "room_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "room_type": "small_room_for_video",
        "created_by": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511",
        "custom_items": {
            "call_quality": "HIGH"
        }
    },
    "invitation": {
            "inviter_id": "4d11f4fb-4808-4049-9bef-25e9cce7bfc4",
            "invitee_id": "5p11t2hw-1234-5678-2pfh-37p8wqp3nxq3"
    }
}

room:invitation_cancel

The following shows a webhook payload of a room:invitation_cancel event.

{
    "category": "room:invitation_cancel",
    "occurred_at": 0,
    "application_id": "",
    "room": {
        "room_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "room_type": "small_room_for_video",
        "created_by": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511",
        "custom_items": {
            "call_quality": "HIGH"
        }
    },
    "invitation": {
            "inviter_id": "4d11f4fb-4808-4049-9bef-25e9cce7bfc4",
            "invitee_id": "5p11t2hw-1234-5678-2pfh-37p8wqp3nxq3"
    }
}

room:invitation_accept

The following shows a webhook payload of a room:invitation_accept event.

{
    "category": "room:invitation_accept",
    "occurred_at": 0,
    "application_id": "",
    "room": {
        "room_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "room_type": "small_room_for_video",
        "created_by": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511",
        "custom_items": {
            "call_quality": "HIGH"
        }
    },
    "invitation": {
            "inviter_id": "4d11f4fb-4808-4049-9bef-25e9cce7bfc4",
            "invitee_id": "5p11t2hw-1234-5678-2pfh-37p8wqp3nxq3"
    }
}

room:invitation_decline

The following shows a webhook payload of a room:invitation_decline event.

{
    "category": "room:invitation_decline",
    "occurred_at": 0,
    "application_id": "",
    "room": {
        "room_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "room_type": "small_room_for_video",
        "created_by": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511",
        "custom_items": {
            "call_quality": "HIGH"
        }
    },
    "invitation": {
            "inviter_id": "4d11f4fb-4808-4049-9bef-25e9cce7bfc4",
            "invitee_id": "5p11t2hw-1234-5678-2pfh-37p8wqp3nxq3"
    }
}

room:invitation_no_answer

The following shows a webhook payload of a room:invitation_no_answer event.

{
    "category": "room:invitation_no_answer",
    "occurred_at": 0,
    "application_id": "",
    "room": {
        "room_id": "D014A053-ED14-4F69-A17C-8832EC8AF52F",
        "room_type": "small_room_for_video",
        "created_by": "user-7553811ae7874fcfa73474b73ccbd4e7-1590570511",
        "custom_items": {
            "call_quality": "HIGH"
        }
    },
    "invitation": {
            "inviter_id": "4d11f4fb-4808-4049-9bef-25e9cce7bfc4",
            "invitee_id": "5p11t2hw-1234-5678-2pfh-37p8wqp3nxq3"
    }
}

On this page

Configuration Webhook endpoint requirements Headers Webhook events Retrieve a list of subscribed events Choose which events to subscribe to Direct call Group call