Calls Platform API v1
Calls Platform API
Calls Platform API
Version 1

Webhooks

Copy link

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

Copy link

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


Webhook endpoint requirements

Copy link

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

Copy link

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

content-type: application/json
...

Webhook events

Copy link
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.

Group call
EventTriggered 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

Copy link

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

HTTP request

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

Parameters

Copy link

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)

?display_all_webhook_categories=true

Response

Copy link

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

Choose which events to subscribe to

Copy link

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.

HTTP request

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

Request body

Copy link

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 allsubscribe selectedunsubscribe all
# Request body example
{
    "enabled": true,
    "url": "https://example.com/calls/notifications",
    "enabled_events": ["*"]
}

Response

Copy link

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

Copy link

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

Copy link

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

Copy link

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

Copy link

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

Copy link

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

Copy link

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

Copy link

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

Copy link

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

Copy link

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

Copy link

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

Copy link

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

Copy link

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

Copy link

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

Copy link

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

Copy link

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