WEBHOOKS

Pushed data

HTTP headers

• X-CALLR-HmacSignature: base64 encoded HMAC signature (defaults to SHA256) of the json payload, if a hmac_secret was provided.
• X-CALLR-EventId: Unique event id. Also available in the body.

JSON payload (Object)

• event_id: Unique ID per event. Useful for idempotence.
• event_at: ISO 8601 datetime at millisecond precision of the event.
• hook_hash: Webhook id. Can be null if dynamic webhook.
• type: Event type.
• try: The try number, starting from 0.
• data: The actual data (always an object).

SMS MT DLR example

This is an example of sms.mt.status_update (SMS DLR).

POST /webhook_path HTTP/1.1
User-Agent: CALLR/API 0.9942
Host: your.url.here
Accept: */*
Content-Type: application/json
X-CALLR-EventId: 942214623559669723oDAOsQafV6EJlx
X-CALLR-HmacSignature: PvVXCkEhG8TpmGW1DTKF2yCljFx4ob+hELnxZfvow2dpWfzuCNLP+IWatocPSRqoPTojLvsPpyGRhFYXFnvrkA==
Content-Length: 1014

{
    "event_at": "2016-05-04T12:29:32.340Z",
    "event_id": "9422146236497234056PGNSmlw2sOrjq",
    "hook_hash": null,
    "try": 0,
    "type": "sms.mt.status_update",
    "data": {
        "b_customer_debit": "8.00",
        "b_customer_mode": "PREPAID",
        "date_creation": "2016-05-04 12:29:32",
        "date_received": "0000-00-00 00:00:00",
        "date_sent": "2016-05-04 12:29:32",
        "date_update": "2016-05-04 12:29:32",
        "encoding": "GSM",
        "from": "SMS",
        "hash": "MTZTAQCH",
        "nature": "MARKETING",
        "network": "",
        "options": {
            "flash_message": false,
            "force_encoding": null,
            "user_data": "",
            "webhook": {
                "endpoint": "http://example.com/webhook_path"
            }
        },
        "parts": 1,
        "status": "SENT",
        "status_error": "",
        "text": "bonjours",
        "to": "+447890123456",
        "type": "OUT",
        "user_data": ""
    }
}

SMS MO example

This is an example of sms.mo.

POST /webhook_path HTTP/1.1
User-Agent: CALLR/API 0.9942
Host: your.url.here
Accept: */*
Content-Type: application/json
X-CALLR-EventId: 942214623559669723oDAOsQafV6ESlx
X-CALLR-HmacSignature: PvVXCkEhG8TpmGW1DTKF2yCljFx4ob+hELnxZfvow2dpWfzuCNLP+IWatocPSRqoPTojLvsPpyGRhFYXFnvrkX==
Content-Length: 925

{
    "event_at": "2016-05-04T12:29:32.340Z",
    "event_id": "9422146236497234056PGNSmlw2sOrjq",
    "hook_hash": null,
    "try": 0,
    "type": "sms.mo",
    "data": {
        "b_customer_debit": "0.00",
        "b_customer_mode": "PREPAID",
        "date_creation": "2016-05-04 12:40:32",
        "date_received": "2016-05-04 12:40:32",
        "date_sent": "0000-00-00 00:00:00",
        "date_update": "2016-05-04 12:40:32",
        "encoding": "GSM",
        "from": "+447890123456",
        "hash": "MTZTAQCH",
        "nature": "MARKETING",
        "network": "",
        "options": {
            "webhook": {
                "endpoint": "http://example.com/webhook_path"
            }
        },
        "parts": 1,
        "status": "RECEIVED",
        "status_error": "",
        "text": "Hello world",
        "to": "+16469820800",
        "type": "IN",
        "user_data": ""
    }
}

HMAC signature

The goal of the signature is to verify both the data integrity, and the authentication of the payload (to make sure it came from us).

When subscribing to an event, you can specify in options:

• hmac_secret: an HMAC secret we will use to sign the JSON payload. Must be a string between 8 and 128 chars.
• hmac_algo: Hash algorithm. Defaults to SHA256 if not specified. Available: MD5, SHA1, SHA256, SHA512.

Here is how you can check the HMAC signature (PHP):

// $secret is the secret you set when subscribing to the webhook

$payload = file_get_contents('php://input'); // HTTP body content

$wanted_signature = base64_encode(hash_hmac('sha256', $payload, $secret, true));
$received_signature = $_SERVER['HTTP_X_CALLR_HMACSIGNATURE']; // X-CALLR-HmacSignature

if ($wanted_signature !== $received_signature) {
    error_log('HMAC verification failed for this request.'); // you might want to log a bit more here.
    return;
}

$event = json_decode($payload);

// now you can access the event properties...
// $event->type
// $event->event_at
// $event->event_id
// $event->data
// etc.


#!/usr/bin/python
import SimpleHTTPServer,SocketServer,base64,hmac,hashlib,json

PORT = 8000

class ServerHandler(SimpleHTTPServer.SimpleHTTPRequestHandler):

    def do_POST(self):
      content_len = int(self.headers.getheader('content-length', 0))
      post_body = self.rfile.read(content_len)
      digested = hmac.new('secr3t_s1gnatur3!FE4R',post_body,hashlib.sha256).digest()
      wanted_signature = base64.b64encode(digested)
      received_signature = str(self.headers.getheader('X-Callr-Hmacsignature', 0))
      if (wanted_signature != received_signature):
        quit()

Handler = ServerHandler
httpd = SocketServer.TCPServer(("", PORT), Handler)
httpd.serve_forever()

Retries

When we POST to your URL, we expect an answer within 10 seconds, with an HTTP reply code between 200 and 299.

If we do not meet these conditions, we will retry at a later time (we wait for #try*10seconds), a maximum of 10 times.

Reference

The webhooks service is documented here.

Example - API init

require 'vendor/autoload.php'; // Composer

$api = new \CALLR\API\Client;
$api->setAuth(new \CALLR\API\Authentication\LoginPasswordAuth('login', 'password'));

var callr = require('callr');
var api = new callr.api(callr.loginPasswordAuth('login', 'password'));

require 'callr'
api = CALLR::Api.new('login', 'password')

import callr
api = callr.Api("login", "password")

        

Example - Subscribing to SMS MO

$type = 'sms.mo';
$endpoint = 'http://yourdomain.com/webhook_path';
$options = null;

$result = $api->call('webhooks.subscribe', [ $type, $endpoint, $options ]);

var type = 'sms.mo';
var endpoint = 'http://yourdomain.com/webhook_path';
var options = null;

api.call('webhooks.subscribe', type, endpoint, options).success(function(response) {
    // success callback
});

type = 'sms.mo'
endpoint = 'http://yourdomain.com/webhook_path'
options = nil

result = api.call('webhooks.subscribe', type, endpoint, options)

type = 'sms.mo'
endpoint = 'http://yourdomain.com/webhook_path'
options = None

result = api.call('webhooks.subscribe', type, endpoint, options)

        

The result is a Webhook object.

Example - Subscribing to SMS MT DLR

$type = 'sms.mt.status_update';
$endpoint = 'http://yourdomain.com/webhook_path';
$options = null;

$result = $api->call('webhooks.subscribe', [ $type, $endpoint, $options ]);

var type = 'sms.mt.status_update';
var endpoint = 'http://yourdomain.com/webhook_path';
var options = null;

api.call('webhooks.subscribe', type, endpoint, options).success(function(response) {
    // success callback
});

type = 'sms.mt.status_update'
endpoint = 'http://yourdomain.com/webhook_path'
options = nil

result = api.call('webhooks.subscribe', type, endpoint, options)

type = 'sms.mt.status_update'
endpoint = 'http://yourdomain.com/webhook_path'
options = None

result = api.call('webhooks.subscribe', type, endpoint, options)

        

The result is a Webhook object.

Example - Subscribing to Inbound Calls with HMAC signature

$type = 'call.inbound_start';
$endpoint = 'http://yourdomain.com/webhook_path';
$options = new stdClass;
$options->hmac_secret = 'secr3t_s1gnatur3!FE4R';
$options->hmac_algo = 'SHA256';

$result = $api->call('webhooks.subscribe', [ $type, $endpoint, $options ]);

var type = 'call.inbound_start';
var endpoint = 'http://yourdomain.com/webhook_path';
var options = {
    hmac_secret: 'secr3t_s1gnatur3!FE4R',
    hmac_algo: 'SHA256'
};

api.call('webhooks.subscribe', type, endpoint, options).success(function(response) {
    // success callback
});

type = 'call.inbound_start'
endpoint = 'http://yourdomain.com/webhook_path'
options = {
    :hmac_secret => 'secr3t_s1gnatur3!FE4R',
    :hmac_algo => 'SHA256'
}

result = api.call('webhooks.subscribe', type, endpoint, options)

type = 'call.inbound_start'
endpoint = 'http://yourdomain.com/webhook_path'
options = {
    'hmac_secret': 'secr3t_s1gnatur3!FE4R',
    'hmac_algo': 'SHA256'
}

result = api.call('webhooks.subscribe', type, endpoint, options)

        

The result is a Webhook object.