Event subscriptions (webhooks)

Overview

Allows you to manage subscriptions to events generated by the system. Applies only to requests authorized through tokens integration channels with type subscr.

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

An arbitrary number of subscriptions can be registered through one integration channel. But each event is sent no more than once to a single integration channel, treating one integration channel entity as one separate instance of the external system. All it takes is one active subscription setting the conditions for sending an event to the current integration channel, suitable for the generated event instance, for it to be sent by the webhook.

At any time, a subscription can be terminated by a deletion request.

In the current version, subscriptions are only valid for the following classes of events:

  • callevents

  • confevents

  • providerevents

  • statesevents

  • Custom events from scripts

Available in working domains only.

Requests

HTTP verb Endpoint Description

POST

/rest/v1/service/webhooks

Subscribe to events

GET

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

Subscription information

PUT

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

Event subscription renewal

DELETE

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

Unsubscribe from events

Subscribe to events

Produces event subscriptions. The subscription ID is returned in the response and can be used to renew and delete subscriptions.

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 is a participant in the call for which the event is generated, the subscription event will be sent. Otherwise it will not.

Specified as a JSON array of objects applied via an ILI operation. Each object has a type field, and depending on its value, additional fields. Combinations of filter fields for event classes.

events

A list of events to be sent by webhooks.

Specified as a JSON array of strings. Each line represents a mask for the event in the format CLASSNAME.EVENTNAME. If * is specified as EVENTNAME, such as "callevents.*", then all events of that class are subscribed to.

expires

Subscription registration period, in seconds.

If there are no renewals after the interval, the subscription is automatically deleted. Maximum value: 86400.

url

Arbitrary URL to send webhooks to.

Optional parameter. The url specified in the associated integration channel is applied by default.
Table 2. Combinations of filter fields for event classes
Event Class Object type (field type) Filter fields by object

callevents

sipuser

Account login SIP-user

callevents

other

Subscriber’s phone number

confevents

conf

Room ID or room number conferences

providerevents

provider

Account code telephony provider

registrarevents

user’s registration, sipuser’s registration

Account ID user, account login SIP-user

statesevents

user, sipuser

Account login user, account login SIP user

Random events

sipuser

Account login SIP-user
Request example
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 of a successful response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

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

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

Subscription information

Displays subscription information by ID.

Request

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

Response

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

{
  "objects": {"sipuser": "sip2", "sipuser": "sip1"},
  "events":["callevents.*", "statesevents.sipuser_state_changed"],
  "url": "http://127.0.0.1"
}
Example of an unsubscribed response (subscription expired)
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[]
Example of an unsuccessful response
404 Not Found
Content-Type: application/json

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

Event subscription renewal

Produces event subscription renewals. Allows changes to the terms and conditions of a previous subscription.

Request

The object fields are similar to query fields POST.

Request example
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 of a successful response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

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

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

Unsubscribe from events

Deletes an existing subscription.

Request

Request example
DELETE /rest/v1/service/webhooks/4e7e9ce0-0621-6606-d157-c00000000004 HTTP/1.1

Response

Response example
HTTP/1.1 200 OK
Content-Type: application/json

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

See also

  • Personalization
  • Increase font size
  • Decrease font size