Skip to main content

Register a webhook

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

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

url​

Type: URL (required)
Webhook target URL.

types​

Type: STRING (required)
Comma separated resource types.

info

Register a webhook by specifying one or more of the following resource types (comma-separated): room_update, recording_update.

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

Example 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

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.

Example webhooks​

Example recording_update​

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

Example room_update​

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.

{
  "timestamp": 1609493400,
  "type": "room_update",
  "room": {
    "id": "63ede350b20526000f64376b",
    "name": "eyeson room",
    "ready": false,
    "started_at": null,
    "shutdown": true,
    "sip": {
      ...
    }
  }
}