Skip to main content

Register a webhook

You can register a single webhook and use the response type to determine its purpose.

info

Each API_KEY supports only ONE webhook configuration. Registering a new webhook will replace any previously registered webhook for that API key.

Webhook Endpoint Requirements

  • Your server (the webhook endpoint) must accept HTTPS POST requests.
  • The body of these requests will be in JSON format.

The webhook's "response type" (or event type) will tell you what the webhook is about. This allows you to handle different events appropriately at the same endpoint. Register a webhook by specifying one or more of the following resource types (comma-separated): room_update, recording_update.

info

In order to get the webhooks endpoint you can retrieve the URL from the response when creating a room.

To verify webhook authenticity, you can validate the request using SHA256 HMAC with your API key - the hash is provided in the X-Eyeson-Signature header.

POST /webhooks
HEADERS Authorization
RESPONSES 201 CREATED, 400 BAD REQUEST, 403 FORBIDDEN
REQUIRED url, types
Req/Res Example: Room Update
Request
curl -X POST -H "Authorization: $API_KEY" -d "url=$TARGET_URL" -d "types=room_update" "https://api.eyeson.team/webhooks"
Response
{
"timestamp": 1609493400,
"type": "room_update",
"room": {
"id": "63ede350b20526000f64376b",
"name": "eyeson room",
"ready": false,
"started_at": null,
"shutdown": true,
"sip": {
...
}
}
}
tip

If you want to build up a meeting history in your application, register a webhook for room_update and track when receiving a room update where shutdown attribute is true.

Req/Res Example: Recording Update
Request
curl -X POST -H "Authorization: $API_KEY" -d "url=$TARGET_URL" -d "types=recording_update" "https://api.eyeson.team/webhooks"
Response
{
"timestamp": 1609493400,
"type": "recording_update",
"recording": {
"id": "63ede57ff3e015000fbe1af5",
"created_at": 1609491600,
"duration": 1800,
"links": {
"self": "https://api.eyeson.team/recordings/63ede57ff3e015000fbe1af5",
"download": "https://fs.eyeson.com/meetings/<key>.webm?..."
},
"user": {
"id": "63ede350b20526000f64376d",
"name": "Jane Doe",
"avatar": "https://myawesomeapp.com/images/avatar.png",
"guest": false,
"joined_at": "2021-01-01T09:00:00.000Z"
},
"room": {
"id": "63ede350b20526000f64376b",
"name": "eyeson room",
"ready": true,
"started_at": "2021-01-01T09:00:00.000Z",
"shutdown": false,
"sip": {
...
},
"guest_token": "gKsiVlrvkFyL3klk1wBHLlm3"
}
}
}

url

Type: URL (required)
Webhook target URL.

types

Type: STRING or Array<String> (required)
Comma separated resource types.

ValueDescription
room_updateTriggered when there is an update to a room.
recording_updateTriggered when there is an update to a recording.
room_update, recording_updateTriggers updates for both room and recording events.

In order to get notified for new recordings in any room session, you can register a webhook upfront, using your target location and the webhook type recording_update. See the recording resource on details of the received JSON document.

Get currently registered webhook

Check the currently registered webhook as well as the last sent message timestamp and response code.

GET /webhooks
HEADERS Authorization
RESPONSES 200 OK, 403 FORBIDDEN
Req/Res Example: Registered Webhooks
Request

curl -X GET -H "Authorization: $API_KEY" "https://api.eyeson.team/webhooks"

Response
{
"id": "63ede98fb20526000f64378a",
"types": [
"room_update"
],
"url": "https://myawesomeapp.com/meeting-webhook",
"last_request_sent_at": "2021-01-01T09:00:00.000+00:00",
"last_response_code": "201"
}

Delete current registered webhook

DELETE /webhooks/`WEBHOOK_ID`
HEADERS Authorization
RESPONSES 204 NO CONTENT, 400 BAD REQUEST, 403 FORBIDDEN, 404 NOT FOUND
Req/Res Example: Delete Registered Webhooks
Request

curl -X DELETE -H "Authorization: $API_KEY" "https://api.eyeson.team/webhooks/$WEBHOOK_ID"

Response
No Response