Security and Authentication

Overview

Callfire supports encrypted communication channels between our endpoints and customer applications. All communications is going through HTTPS protocol, we are using TLS since SSLv3 is deprecated and isn't secure anymore. Also we use SSL certificates for subscription and webhook calls so clients can whitelist it to authorize connections from our servers.

API Authentication

The CallFire API v1.1 and v2 uses HTTP Basic Authentication to verify the user of an endpoint, more information about basic authentication you can find at wiki page. To get API credentials pair please follow this guide then generated username/password should be sent in Authorization header.

Example of generated API credentials

Username: a6343cc4edd6
Password: c2d77eec4aa3e224

The header that the user sends looks like this:

Authorization: Basic YTYzNDNjYzRlZGQ2OmMyZDc3ZWVjNGFhM2UyMjQ=

That is all that is needed to authenticate to the CallFire API. NOTE: A standard CallFire UI username and password will not work as API credentials. One must generate credentials for this authentication to work. In case you send incorrect username/password pair our server will respond with 401 Unauthorized response code.

API v1.1 Subscriptions and v2 Webhooks security

Subscriptions in API v1.1 and Webhooks in API v2 can be created only via an authenticated API call, we support secured HTTPS connections to client application as well as unsecured HTTP calls, but we strongly recommends to use HTTPS endpoints in order to secure your information. Subscriptions and Webhooks are HTTP POST calls made upon some event e.g. voice/text campaign has started/stopped, you've got incoming text, outbound call has started/finished and many more.

To set up a secured notification or webhook you should:

1. configure HTTPS endpoint on your end e.g. https://callback-service.com/listener (you can use trusted or self-signed certificate)
2. create a notification or webhook via API POST call to corresponding URI, see CURL examples below: [[code-container]] [+subscription] request:

   #!/usr/bin/env bash
   
   curl https://www.callfire.com/api/1.1/rest/subscription.json \
       -X POST \
       -u login:password \
       -d Endpoint=https://callback-service.com/listener \
       -d NotificationFormat=JSON \
       -d TriggerEvent=OUTBOUND_TEXT_FINISHED

   response:

   {
       "ResourceReference": {
           "Id":609951003,
           "Location":"https://www.callfire.com/api/1.1/rest/subscription/609951003"
       }
   }

   [-subscription] [+webhook] request:

   #!/usr/bin/env bash
   
   curl -u username:password -H "Content-Type:application/json" -X POST "https://api.callfire.com/v2/webhooks" -d '
       {
           "name":"Sms sent",
           "resource":"OutboundText",
           "events":["Finished"], 
           "callback":"https://callback-service.com/listener"
       }'

   response:

   {
     "id": 4321
   }

   [-webhook] [[/code-container]]
3. depending on your server configure it to accepts Callfire's client certificate.

Whitelisting CallFire' IP addresses

Our services are based on dynamic cloud infrastructure and IP addresses of our servers can be changed dynamically thus we don't provide the list of IP addresses to whitelist.

To make sure the incoming request came from CallFire you can use the secret token for your webhook to let CallFire sign the request, then you can validate it on your side and reject if signature isn't matched. For more information on how to create a webhook with token read webhooks guide