Webhooks from TTNC come in the form of HTTP POST requests with the HTTP request body consisting of a JSON string containing the relevant information for the webhook event. Depending which webhook you are receiving will depend on the schema of the JSON. At the bottom of this page you will find a reference to all webhooks and their particular schemas and information regarding how to set up webhooks in myTTNC.
Using webhooks
To set up a webhook, you will first need to create an 'Application' in myTTNC. An Application is primarily used to access the TTNC API in order to make changes to your account and numbers, as well as to pull data from your account. However Applications are also used for webhoooks.
When creating an Application, you will be asked for a Description, which is simply a friendly name for your reference. You will also be asked for IP addresses which are used to verify you access to the TTNC API. As much as these IP addresses will not be used for webhooks, at least one IP address is required to create an Application in myTTNC. You will need to fill out the "Webhook URL" field in order to receive webhooks and this should be a URL to your system where you are expecting to receive the webhook and its information.


Enabling specific webhooks
Once you have created your Application including your webhook URL, you will need to set up each webhook you want to use for whichever services are applicable on your telephone numbers. Simply click on the blue 'Edit; button next to any number, and scroll down until you find "Configure Webhook".


Please note:
Some webhooks can be configured on specific parts of your telephone number setup, for example if you have Virtual Receptionist (menu options) then you can set up webhooks for each option individually by navigating to those options settings.
Then simply select the name of the Application to be used for the webhook event, and click confirm to save these settings.


Once the confirmation box appears everything will be set up and webhooks will start to be sent to your webhook URL as soon as applicable events happen to your telephone number.
Authenticating webhooks from myTTNC
We've also built authentication into our webhooks, in the form of a signed signature sent in the HTTP header, so you can verify the source and payload. While not required, it would be good practice to verify the signature prior to accepting the webhook. The header in question will look like the following;
Webhook-Signature : 098f6bcd4621d373cade4e832627b4f6098f6bcd4621d373cade4e832627b4f6
We sign the body of the POST request with an HMAC SHA256 hex digest, using the secret for the Application which can be found in myTTNC. The secret can be found by clicking the edit button next to the appropriate webhook on the Applications page in myTTNC.


Webhooks for Inbound Calls
Webhooks can be triggered whenever someone makes a call to your virtual telephone number or if you have it set it, when they select a Virtual Receptionist menu option.
Once you have created your Application including your webhook URL, you will need to set up each webhook you want to use for whichever services are applicable on your telephone numbers. Simply click on the blue 'Edit' button next to any number, and scroll down until you find "Configure Webhook".


Then simply select the name of the Application to be used for the webhook event, and click confirm to save these settings.


You're now ready to receive webhooks. The following information outlines how the information will be sent to you, and details about what each field means in relation to the event.
JSON Payload (start of call & call progress)
When this webhook is enabled you will receive a JSON payload whenever a caller dials the TTNC Number in question. You will also receive a JSON payload whenever the caller moves through any option based menus, if you have set up the webhook on these menu options.
{
"event" : {
"anumber" : "01245012345",
"anumber_contact_name": "Office",
"bnumber" : "02031511000",
"bnumber_tags" : [],
"bnumber_alias" : "Main Line",
"call_date" : "2016-05-24",
"call_time" : "11:14:39",
"option" : "-",
"ref" : "!5442B5AD54E14",
"event_type" : "incoming_call"
}
}
string anumber | The callers CLI (telephone number). |
---|---|
string anumber_contact_name | This is the Contact Name assigned to the Telephone Number (CLI) and Address Book entry which are manually entered or assigned from an Inbound Call. If you don’t have a Contact assigned to the Inbound CLI, this field defaults to “-”. |
string bnumber | The TTNC number that's being called. |
array bnumber_tags | This will contain all TAGS associated with the TTNC Number and will show in this format [ “tag1" , “tag2” ]. If you don’t have any TAGS set up, this field defaults to [ ]. |
string bnumber_alias | This is the Alias or Nickname of the TTNC Number. If you don’t have a Number Alias or Nickname set up, this field defaults to “-”. |
string call_date | The date of the start of the call. |
string call_time | The time of the start of the call. |
string ref | The CDR Ref for the call - this can be used after the call has finished to identify the call. CDRs can be pulled using the TTNC API by using NoveroCDR requests. |
string option | If you have Virtual Receptionist (menu option based forwarding) enabled on your number then this is the position in the call flow. Webhooks need to be set up on each option in order to be triggered. Virtual Receptionist examples:
If you have no Virtual Receptionist set up, this field defaults to "-". |
string event_type | The type of webhook. |
JSON Payload (call roundup)
When this webhook is enabled you will receive a JSON payload whenever a call finishes. This will contain all of the information for the call, including the duration of the call, call cost and several other pieces of information explained below;
{
"event": {
"ref": "!8D3B9C8356C04",
"call_date": "2016-05-24",
"call_time": "11:14:39",
"anumber" : "01245012345",
"anumber_contact_name": "Office",
"anumber_type": "UK Chelmsford",
"bnumber" : "02031511000",
"bnumber_tags" : [],
"bnumber_alias" : "Main Line",
"bnumber_type": "UK London",
"dialled": "447777777777",
"dialled_type": "UK Mobile",
"duration": "45",
"duration_system": "45",
"cost": 0.075,
"reason": "1",
"reason_q805": "16",
"event_type": "cdr"
}
}
string ref | The CDR Ref for the call - this can be used after the call has finished to identify the call. CDRs can be pulled using the TTNC API by using NoveroCDR requests. |
---|---|
string call_date | The date of the start of the call. |
string call_time | The time of the start of the call. |
string anumber | The telephone number of the caller. |
string anumber_type | The location or network of the caller. |
string anumber_contact_name | This is the Contact Name assigned to the Telephone Number (CLI) and Address Book entry which are manually entered or assigned from an Inbound Call. If you don’t have a Contact assigned to the Inbound CLI, this field defaults to “-”. |
string bnumber | The TTNC number that's being called. |
string bnumber_type | The location or type of TTNC number being called. |
array bnumber_tags | This will contain all TAGS associated with the TTNC Number and will show in this format [ “tag1" , “tag2” ]. If you don’t have any TAGS set up, this field defaults to [ ]. |
string bnumber_alias | This is the Alias or Nickname of the TTNC Number. If you don’t have a Number Alias or Nickname set up, this field defaults to “-”. |
string dialled | The telephone number of the forwarding destination which answered the call. |
string dialled_type | The location or network of the forwarding destination which answered the call. |
string duration | The duration of the call which was connected to the forwarding destination. |
string duration_system | The duration of the call which was connected to TTNC services (Virtual Receptionist, Call Greeting, etc). |
float cost | The amount of call credit deducted from your account to pay for the call (ex VAT). |
string reason | The clearing code for the call. Reason 1 means a completed call, for other reasons codes, please contact support. |
string reason_q805 | Additional clearing code for the call. Reason 1 means a completed call, for other reasons codes, please contact support. |
string event_type | The type of webhook. |
Webhooks for Inbound SMS messages
Whenever your virtual UK Geographic number receives an SMS message, we can send you webhook notifications.
Once you have created your Application including your webhook URL, you will need to set up the SMS webhook through myTTNC; simply click on the blue 'Edit; button next to any number, and scroll down until you find "Configure Webhook".


Then simply select the name of the Application to be used for the webhook event for the SMS webhook option and click confirm to save these settings.


As soon as you've confirmed the webhook settings, we'll start sending webhook notifications to you webhook URL whenever an SMS is received to your number. The following information outlines how the information will be sent to you, and details about what each field means in relation to the event.
{
"event": {
"event_type" : "incoming_sms",
"originator" : "44777777777",
"bnumber" : "02031511000",
"sms_date" : "2016-05-24",
"sms_time" : "11:29:48",
"message_id" : 363723,
"message" : "This is a test message",
"udh" : "0500035D0302"
}
}
string event_type | The type of webhook. |
---|---|
string originator | The telephone number of the sender. |
string bnumber | The TTNC telephone number the SMS was sent to. |
string sms_date | The date that SMS was sent. |
string sms_time | The time that SMS was sent. |
int message_id | The unique identifier for the SMS. |
string message | The content of the SMS. |
string udh | "User Data Header" is binary structure which determines extra information about the SMS message. This is usually present when the SMS is part of a larger message which was over the 160 character limit for a single SMS. The UDH information will allow you to be able to rejoin the SMSs into the larger message if you desired. In order to determine which SMSs are related to each other in this way you must look at the last 6 characters of the UDH. For the example; "0500035D0302" you take the last 6 characters "5D0302" and split these into the pairs "5D", "03" "02".
We can infer that there is a "0500035D0201" for the first part of the message, and a "0500035D0203" for the last part of the message |
Set up or remove Webhook Applications for a number
SetApplication
Description
This allows you to set up, change or remove which myTTNC Application is being used for particular webhooks on a number.
string Number | The TTNC number which is to be modified. |
---|---|
int call_api_vkey_id | The ID of the application (obtained from NoveroVKeys::ListApplications) to be used for the webhook. To disassociate any application from the webhook set this parameter to -1. The Application for the set ID must have a Webhook URL associated with it. The 'call_api_vkey_id' webhook relates to Webhooks for inbound calls. |
int sms_api_vkey_id | The ID of the application (obtained from NoveroVKeys::ListApplications) to be used for the webhook. To disassociate any application from the webhook set this parameter to -1. The Application for the set ID must have a Webhook URL associated with it. The 'sms_api_vkey_id' webhook relates to Webhooks for inbound SMS. |
In order to get a successful response, at least one of the optional parameters must be sent, however it is possible to send several of the optional parameters together in one request as shown in the examples below.
<?xml version="1.0"?>
<NoveroRequest>
<Request target="NoveroNumbers" name="SetApplication" id="TestRequest">
<Number>01245123456</Number>
<call_api_vkey_id>999</call_api_vkey_id>
<sms_api_vkey_id>999</sms_api_vkey_id>
</Request>
</NoveroRequest>
<?php
require_once('TTNCApi.php');
$Api = new TTNCApi('<username>', '<password>', '<VKey>');
$Request = $Api->NewRequest('NoveroNumbers', 'AddTag', 'TestRequest');
$Request->SetData('Number', '01245123456');
$Request->SetData('call_api_vkey_id', 999);
$Request->SetData('sms_api_vkey_id', 999);
$Api->MakeRequests();
$Response = $Api->GetResponseFromId('TestRequest');
?>
require TTNCApi
api = TTNCApi.new('<username>', '<password>', '<vkey>')
request = api.newrequest('NoveroNumbers', 'SetApplication', 'TestRequest')
request.setdata('Number', '01245123456')
request.setdata('call_api_vkey_id', 999)
request.setdata('sms_api_vkey_id', 999)
api.makerequest()
p request.getresponse()
api = TTNCApi('<username>', '<password>', '<vkey>')
request = api.newrequest('NoveroNumbers', 'SetApplication', 'TestRequest')
request.setdata('Number', '01245123456')
request.setdata('call_api_vkey_id', 999)
request.setdata('sms_api_vkey_id', 999)
api.makerequest()
p request.getresponse()
using System;
using TTNCApi;
class Program
{
static void Main(string[] args)
{
TTNCApi api = new TTNCApi("<username>", "<password>", "<vkey>");
TTNCRequest request = api.NewRequest("NoveroNumbers", "SetApplication", "TestRequest");
request.setData("Number", "01245123456");
request.setData("call_api_vkey_id", 999);
request.setData("sms_api_vkey_id", 999);
api.MakeRequests();
TTNCParser dic = request.GetResponse();
}
}
Response
<?xml version="1.0"?>
<NoveroResponse>
<Response target="NoveroNumbers" name="SetApplication" Code="200" RequestId="TestRequest">
<ResponseMessage>Application set successfully</ResponseMessage>
<Success>Application set successfully</Success>
</Response>
</NoveroResponse>
Updated about a year ago
Further reading....
API |
API library downloads |
Triggering Webhooks in Zapier |