Event subscriptions (webhooks)

Overview

Allows managing subscriptions to system-generated events. Webhooks are an alternative to WebSocket subscriptions (Token API) for external systems that cannot maintain a persistent connection. Using webhooks is not recommended: each notification is sent as a separate HTTP POST request with a new connection, synchronously and sequentially for one address, without confirmation or retries. A slow receiver delays other notifications to its address, and if the receiver is unavailable the notification is lost (more). Data model events (modelevents) are not available via webhooks.

The webhook request format is set by the integration channel ext.http_notify_format field (more): by default — POST with a JSON notification body. Applies only to requests authorized via tokens of integration channels with type subscr.

Based on the subscription, the system sends webhooks to the address specified in the integration channel url field. The subscription requires regular renewal at an interval not exceeding the subscription registration period specified in the request (the expires field).

Any number of subscriptions can be registered through one integration channel. If an event matches several subscriptions, a webhook is sent for each of them (with the subscription identifier in the sid field).

At any time the subscription can be terminated with a delete request.

In the current version the subscription applies only to the following event classes:

  • callevents

  • confevents

  • providerevents

  • statesevents

  • Custom events from scripts

Available only in working domains.

Requests

HTTP verb Endpoint Description

POST

/rest/v1/service/webhooks

Subscribing to events

GET

/rest/v1/service/webhooks/<id>

Subscription information

PUT

/rest/v1/service/webhooks/<id>

Renewing the event subscription

DELETE

/rest/v1/service/webhooks/<id>

Canceling the event subscription


Subscribing to events

Subscribes to events. The subscription identifier is returned in the response and can be used to renew and delete the subscription.

Request

Table 1. Object fields
Field Description

objects

Filter by objects to which generated events are bound.

For an event to be sent by subscription, it must be bound to at least one of the specified objects. For example, if the user specified in the filter participates in the call for which the event was generated, the event is sent by subscription. Otherwise not.

Specified as the string "any" (no filter) or a JSON array of objects combined with OR. An object is specified as a string (for example "sip1") or as {"type": "sipuser", "sipuser": "sip1"}: the value is taken from the field named by the type. Objects for event classes.

events

List of events to be sent by webhooks.

Specified as a JSON array of strings. Each string is a mask for an event in the CLASSNAME.EVENTNAME format. If the * character is specified as EVENTNAME, for example "callevents.*", the subscription covers all events of that class.

expires

Subscription registration period, in seconds.

Without renewal, the subscription is automatically deleted after the interval expires. Maximum value: 86400. A larger value is reduced to the maximum. The applied value is returned in the response in the expires field.

url

Arbitrary URL for sending webhooks.

Optional parameter. Applies only if the associated integration channel has no url set.

Table 2. Objects for event classes
Event class Object type (type field) Value

callevents

sipuser

Login of the SIP user account

callevents

other

Subscriber telephone number

confevents

conf

Identifier or room number of the conference

providerevents

provider

Account code of the telephony provider

statesevents

user, sipuser

User account identifier, SIP user account login

Custom events

sipuser

Login of the SIP user account

Example request
POST /rest/v1/service/webhooks HTTP/1.1
Content-Type: application/json
Authorization: Bearer 522f62e0b5e731cd507e20bc888c53d5

{
  "objects": [
    {
      "type":"sipuser",
      "sipuser":"sip1"
    },
    {
      "type":"sipuser",
      "sipuser":"sip2"
    }
  ],
  "events": [
    "callevents.*",
    "statesevents.sipuser_state_changed"
  ],
  "expires": 1800
}

Response

Example successful response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "4e7e9ce0-0621-6606-d157-c00000000004",
  "msg": "subscribed",
  "expires": 1800
}
Example failed response
404 Not Found
Content-Type: application/json

{
  "error_code": 1404,
  "error_message": "Token not found"
}

Subscription information

Outputs subscription information by ID.

Request

Example request
GET /rest/v1/service/webhooks/4e7e9ce0-0621-6606-d157-c00000000004 HTTP/1.1
Authorization: Bearer 522f62e0b5e731cd507e20bc888c53d5

Response

Example successful response (with an active subscription)
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "objects": ["sip2", "sip1"],
  "events": ["callevents.*", "statesevents.sipuser_state_changed"],
  "url": "http://127.0.0.1",
  "expires": 296
}

The expires field in the response is the remaining subscription time in seconds.

Example response without subscriptions (subscription expired)
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[]
Example failed response
404 Not Found
Content-Type: application/json

{
  "error_code": 1404,
  "error_message": "Token not found"
}

Renewing the event subscription

Renews the event subscription. Allows changing the terms of the previous subscription.

Request

Object fields are similar to the POST request fields.

Example request
PUT /rest/v1/service/webhooks/4e7e9ce0-0621-6606-d157-c00000000004 HTTP/1.1
Content-Type: application/json
Authorization: Bearer 522f62e0b5e731cd507e20bc888c53d5

{
  "objects": [
    {
      "type":"sipuser",
      "sipuser":"sip1"
    },
    {
      "type":"sipuser",
      "sipuser":"sip2"
    }
  ],
  "events": [
    "callevents.*"
  ],
  "expires": 1800
}

Response

Example successful response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "4e7e9ce0-0621-6606-d157-c00000000004",
  "msg": "subscribed",
  "expires": 1800
}
Example failed response
404 Not Found
Content-Type: application/json

{
  "error_code": 1404,
  "error_message": "Token not found"
}

Canceling the event subscription

Deletes the existing subscription.

Request

Example request
DELETE /rest/v1/service/webhooks/4e7e9ce0-0621-6606-d157-c00000000004 HTTP/1.1

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "4e7e9ce0-0621-6606-d157-c00000000004",
  "msg": "unsubscribed"
}

See also