Methods

Objects

WEBHOOKS

Unleash the power of hooks.

Receive a JSON payload when events occur on our platform.

With webhooks, you can subscribe to events. We will push a JSON payload to your URL whenever the event occur.

Summary

    Events

    Event Description Object pushed
    billing.credit Credit event on your prepaid balance. Webhook.Event.Billing.Credit
    billing.credit_warning Your prepaid balance has reached its warning level. Webhook.Event.Billing.Credit
    billing.credit_shutdown Your prepaid balance has reached its shutdown level. Your account is suspended. Webhook.Event.Billing.Credit
    call.inbound_start An inbound call just started. CDR.In
    call.inbound_hangup An inbound call just hung up. CDR.In
    call.outbound_start An outbound call just started. CDR.Out
    call.outbound_hangup An outbound call just hung up. CDR.Out
    did.assigned A DID was assigned to your account. DID
    did.unassigned A DID was unassigned from your account. DID
    job.status_update A background job has an updated status. Job
    media.library.status_update A Media Library has an updated status. Media.Library
    media.recording.new A Media Recording has been created (like a call recording, a voicemail, etc.). Media.Recording
    media.recording.status_update A Media Recording has an updated status. Media.Recording
    sms.mo An inbound SMS (MO) has been received. SMS
    sms.mt.status_update An outbound SMS (MT) has an updated status. SMS

    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)


    The object we push is of type Webhook.Event. Its properties are:
    • 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

    Method

    Objects

    • Webhook
    $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

    Method

    Objects

    • Webhook
    $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

    Method

    Objects

    • Webhook
    • Webhook.Options
    $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.