Webhooks
Webhooks are HTTP requests that the system sends out that are triggered by certain events. These URLs carry some action information (like a command and related parameters) within the URL, the headers and body to the receiving party which can then take action on it accordingly. For example, an event like "making a call" can trigger a webhook which informs a remote entity (say a billing system) that a call was made and also, who made the call to whom and for how long. Upon receiving the information, the billing system could log it for billing.
Previous versions were using the term "Action URL". The term goes back more than 20 years in the VoIP industry, e.g. for triggering a HTTP request from a VoIP phone. Today the term "webhook" is used most of the time.
For each available event, the system keeps one webhook parameter set. By default the set is empty and no action is taken. However when the event is set the system will trigger the webhook.
Webhooks are available on system, tenant and on account level. There are various events available; they all take the same parameters. Depending on the event, certain variables are availble (see below).
Settings
Authentication method: The system supports the following authentication methods:
- None: No additional header is sent. Authentication information can still be added e.g. to the URL when needed.
- Basic: The Basic authentication header will be used (see RFC 7617). The system will replace the actual authentication information in the log with
*characters. - Rackspace: A special method for Rackspace.
- DNS Made Easy: A special method for DNS made easy.
Username, Password: These fields contain the authentication information. The username is available in the URL as {user} and the password as {pass}.
Region: For some providers, a region is needed.
Method: The HTTP method that will be used for the request.
URL: The HTTP URL that will be used for the request. The request needs to contain the scheme (e.g. https). Variables will be replaced in the URL in URL-encoded format.
Additional headers: This field contains additional headers that will be inserted in the request. Variables will be inserted without any specific encoding.
Encoding for the message body: This setting controls how variables in the body are encoded. It will also set the Content-Type header unless it occurs in the additional headers.
Message body: The body of the message. Variables will be inserted in the selected encoding.
When the system searches for brace replacements, it will skip patterns that are not defined. For example a pattern like {{asset}} will not be changed during the replacement process.
Tenant Level Events
When a wake-up call was programmed
When a wake-up call is entered by the user, the system can trigger a HTTP requests that may trigger further actions. The following variables are available:
| Parameter | Value |
|---|---|
{domain} | The DNS address of the tenant in which the event happened. |
{extension} | The account name of the extension. |
{email_address} | This contains the email address or addresses of the extension. |
{email_vmail} | The setting that tells the PBX weather to send a voicemail to the user, and if to attach the WAV file. |
{parm1}, {parm2} and {parm3} | A copy of the parameters 1, 2 and 3 of the extension. |
{wakeuptime} | The time that was set (only for programmed event). |
When a wake-up call was successfully delivered
When a wake-up call was successfully delivered, the system can trigger a HTTP requests that may trigger further actions. The variables are the same like for the "When a wake-up call was programmed" call.
When a wake-up call is missed
When a wake-up call failed, the system can trigger a HTTP requests that may trigger further actions. The variables are the same like for the "When a wake-up call was programmed" call.
When turning DND on
When the user turned DND on, the system can trigger a HTTP requests that may trigger further actions. The following variables are available:
| Parameter | Value |
|---|---|
{domain} | The DNS address of the tenant in which the event happened. |
{extension} | The extension ID of the user. |
{state} | The state of DND. |
{duration} | The duration for the DND. |
{forward} | The number where calls are being forwarded. |
{reason} | The reason for DND (provided by the user). |
When turning DND off
When the user turned DND off, the system can trigger a HTTP requests that may trigger further actions. The following variables are available:
| Parameter | Value |
|---|---|
{domain} | The DNS address of the tenant in which the event happened. |
{extension} | The extension ID of the user. |
{state} | The state of DND. |
When hotel room is cleaned
When a room cleanup code was called, the system can trigger a HTTP requests that may trigger further actions. The following variables are available:
| Parameter | Value |
|---|---|
{domain} | The DNS address of the tenant in which the event happened. |
{extension} | The extension ID of the user. |
When someone is calling an emergency number
This request is triggered when someone dials an emergency number. There are several variables available for this request:
| Parameter | Value |
|---|---|
{domain} | The DNS address of the tenant in which the call happened. |
{domain-display} | The name of the tenant in which the call happened. |
{lang} | The language code for the call. |
{emergencynumber} | The number that has been dialed. |
{hasuser} | true if the call originated from a account on the system, otherwise false. |
{extension} | The account name of the user. |
{user-name} | The name of the user. |
{user-building} | The bulding of the user. |
{user-room} | The room of the user. |
{user-department} | The department of the user. |
{user-position} | The position of the user if available. |
{from-number} | The caller number is it was dialed. |
{from-name} | The caller name is it was dialed. |
{to-number} | The callee number is it was dialed. |
{to-name} | The callee name is it was dialed. |
{timezone} | The time zone of the call. |
{year}, {month}, {day} | The day of the call. |
{hour}, {minute}, {second} | The time of the call. |
{time}, {date} | The day and time of the call in readable format. |
{epoch} | The time in seconds since 1970. |
{haslocation} | true if the call has a location available. |
{location-comment} | The assigned comment for the location, if available. |
{location-name} | The assigned name for the location, if available. |
{location-street} | The street for the location, if available. |
{location-apartment} | The apartment for the location, if available. |
{location-city} | The city for the location, if available. |
{location-state} | The state for the location, if available. |
{location-zip} | The ZIP code for the location, if available. |
{location-country} | The country for the location, if available. |
{location-latitude} | The latitude for the location, if available. |
{location-longitude} | The longitude for the location, if available. |
{parm1}, {parm2} and {parm3} | A copy of the parameters 1, 2 and 3 of the extension. |
When a new call comes in
This request is triggered when a new call is started. See also the integration framework for an alternative way to report incoming calls. There are several variables available for this request:
| Parameter | Value |
|---|---|
{id} | The internal ID for the call. |
{from} | The "From" header for the call. |
{from-ani-raw} | The username part of the "From" header as it was received. |
{from-ani} | The username part of the "From" header in the domain country code representation. |
{from-ani-e164} | The username part of the "From" header in E164 format. |
{from-ani-nanpa} | The username part of the "From" header in NANPA format. |
{from-ani-plus} | The username part of the "From" header in a global format. |
{from-ani-row} | The username part of the "From" header in ROW-format. |
{from-display} | The display-name part of the "From" header. |
{to} | The "To" header for the call. |
{to-ani-raw} | The username part of the "To" header as it was received. |
{to-ani} | The username part of the "To" header in the domain country code representation. |
{to-ani-e164} | The username part of the "To" header in E164 format. |
{to-ani-nanpa} | The username part of the "To" header in NANPA format. |
{to-ani-plus} | The username part of the "To" header in a global format. |
{to-ani-row} | The username part of the "To" header in ROW-format. |
{to-display} | The display-name part of the "To" header. |
{callid} | The Call-ID for the call |
{domain} | The DNS address of the tenant in which the call happened. |
{lang} | The language code that was assigned to the call. |
{clip} | trueor falsefor CLIP. |
{extension} | The extension ID of the user that started the call, if available. |
{trunk} | The name of the trunk, if available. |
{source} | The source address for the call. |
{target} | The destination for the call in global format. |
{target-ani} | The target in the domain country code representation. |
{target-ani-e164} | The target in E164 format. |
{target-ani-nanpa} | The target in NANPA format. |
{target-ani-plus} | The target in a global format. |
{target-ani-row} | The target in ROW-format. |
When a call connects to an agent
This request is triggered when a call gets connected to an ACD agent. There are several variables available for this request (the from-* and to-* variables were added in 67.0.5):
| Parameter | Value |
|---|---|
{id} | The internal ID for the call. |
{domain} | The DNS address of the tenant in which the call happened. |
{from} | The "From" header for the call. |
{from-ani-raw} | The username part of the "From" header as it was received. |
{from-ani} | The username part of the "From" header in the domain country code representation. |
{from-ani-e164} | The username part of the "From" header in E164 format. |
{from-ani-nanpa} | The username part of the "From" header in NANPA format. |
{from-ani-plus} | The username part of the "From" header in a global format. |
{from-ani-row} | The username part of the "From" header in ROW-format. |
{from-display} | The display-name part of the "From" header. |
{to} | The "To" header for the call. |
{to-ani-raw} | The username part of the "To" header as it was received. |
{to-ani} | The username part of the "To" header in the domain country code representation. |
{to-ani-e164} | The username part of the "To" header in E164 format. |
{to-ani-nanpa} | The username part of the "To" header in NANPA format. |
{to-ani-plus} | The username part of the "To" header in a global format. |
{to-ani-row} | The username part of the "To" header in ROW-format. |
{to-display} | The display-name part of the "To" header. |
{callid} | The Call-ID for the call. |
{lang} | The language code that was assigned to the call. |
{clip} | trueor falsefor CLIP. |
{extension} | The extension ID of the agent. |
{group} | The ID of the call queue (ACD). |
In addition to the from-* and to-* variables there are also orig-from-* and orig-to-* variables available that show the valud when the call entered the tenant.
When a trunk call was made
When an outbound trunk call is made by an agent, the system can trigger a HTTP requests that may trigger further actions. The following variables are available:
| Parameter | Value |
|---|---|
{domain} | The DNS address of the tenant in which the call happened. |
{from} | The "From" header for the call. |
{to} | The "To" header for the call. |
{duration} | The duration of the call, in full minutes. |
When a new mailbox message is available
When a user in the domain has received a new mailbox message, the system can send out a webhook that contains information about the message. The following variables are available:
| Parameter | Value |
|---|---|
{domain} | The DNS address of the tenant in which the event happened. |
{extension} | The extension ID of the user. |
{display} | The extension name of the user. |
{title} | The title for the user. |
{department} | The department of the user. |
{building} | The building of the user. |
{room} | The room of the user. |
{from} | The caller-ID of the one who left the message. |
{to} | The called number. |
{start} | A timestamp when the message was received. |
{duration} | The duration of the message. |
{filename} | The filename on the file system for the message. |
{mp3} | The filename on the file system for the message if a MP3 file is available. |
{new} | A flag that shows if the message was already read by the user or marked as read. |
{attribute} | The attribute for the message, e.g. "urgent" or "private". |
{type} | The type of the message, typically "msg" for a voicemail message. |
{callid} | The Call-ID of the message. |
{cell} | A list of the cell phone that was assigned to the user. |
{email_address} | This contains the email address or addresses of the user. |
{email_vmail} | The setting that tells the PBX weather to send a voicemail to the user, and if to attach the WAV file. |
{parm1}, {parm2} and {parm3} | A copy of the parameters 1, 2 and 3 of the extension. |
{text} | The text from the voice to text transcription (if available). |