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 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
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
| Field | Description |
|---|---|
|
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 |
|
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 |
|
Subscription registration period, in seconds. Without renewal, the subscription is automatically deleted after the interval expires.
Maximum value: |
|
Arbitrary URL for sending webhooks. Optional parameter. Applies only if the associated integration channel has no |
| Event class | Object type (type field) | Value |
|---|---|---|
|
|
Login of the SIP user account |
|
|
Subscriber telephone number |
|
|
Identifier or room number of the conference |
|
|
Account code of the telephony provider |
|
|
|
|
|
Login of the SIP user account |
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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"id": "4e7e9ce0-0621-6606-d157-c00000000004",
"msg": "subscribed",
"expires": 1800
}
404 Not Found
Content-Type: application/json
{
"error_code": 1404,
"error_message": "Token not found"
}
Subscription information
Outputs subscription information by ID.
Request
GET /rest/v1/service/webhooks/4e7e9ce0-0621-6606-d157-c00000000004 HTTP/1.1
Authorization: Bearer 522f62e0b5e731cd507e20bc888c53d5
Response
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.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[]
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.
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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"id": "4e7e9ce0-0621-6606-d157-c00000000004",
"msg": "subscribed",
"expires": 1800
}
404 Not Found
Content-Type: application/json
{
"error_code": 1404,
"error_message": "Token not found"
}
See also
-
Script component Generate custom event.
-
Integration channel entity
-
Subscription to events via WebSocket connection