Follow

SMS Sync Webhook API

SMS Sync Webhook API

This REST API, which you implement on your system, allows Kahuna to send you SMS do not call or opt-in information it receives as it runs your campaigns. This information helps you avoid sending an SMS message from your own system if Kahuna has already detected the do not call and enables you to start resending messages to users who have opted back in.

To ensure Kahuna can transmit its information to you, use the following REST specifications when you implement your API.

REST API Incoming Request Specification

HTTPS Endpoint
  1. Create an HTTPS endpoint in a web server in your system. For example:

    https://YOUR_DOMAIN/api/sms_callback.

  2. Contact your Kahuna Customer Success specialist and ask to register your endpoint.
Signature Header and Validation

In the code that handles incoming REST requests, validate the Kahuna request by checking the request's signature:

  1. Create a string that contains a concatenation of all the phone numbers in the payload, in alphabetical order, with no separator characters. Incoming Request Body describes the format of the incoming request payload.
  2. Generate a keyed-hash message authentication code (HMAC) using the SHA1 cryptographic hash function (see the Wikipedia article Hash based message authentication code. For a key, use your namespace API Key.

    The API Key for the namespace is Available in Settings.

    The result is a binary signature.

  3. Encode this binary signature in Base64 (see the Wikipedia article Base64).
  4. Compare the Base64-encoded value to the value in the X-Kahuna-Signature HTTP request header.
Incoming HTTP Request Headers

The following list describes the HTTP request headers:

Content-Type: application/json

Accept-Charset: UTF-8

Validation: The HTTP Header X-Kahuna-Signature provides a validation signature.

Incoming Request Body

The incoming request body contains SMS do not call and opt-in information that Kahuna receives when running your campaigns.

The format of the request body is an array of dictionaries, described below.

Parameters
number Required. A string that identifies the mobile phone number.
timestamp

Required. The time Kahuna received the do not call or opt-in information, in seconds since the Unix epoch.

opt-in

true if the user opted back in by texting START, YES, or UNSTOP.

The opt-in parameter is omitted if the mobile phone number is unreachable (the number is invalid or there is no routing) or the user opted out by texting STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, or QUIT.

Note: Opt-In information is sent in real time as Kahuna receives inbound messages opting back into SMS. Do Not Call information is batched periodically and sent.

Example

The following is an incoming request.

[
    {
        "number": "1234567890123",
        "timestamp": 1476547200
    },
    {
        "number": "1234567890123",
        "timestamp": 1477605600,
        "opt-in": true
    }
]

API Response

Respond to incoming requests with one of the following three HTTP status codes:

Codes
200

You received and validated the request. If you do not respond with this value within one minute, Kahuna re-sends the request and includes any additional errors it has received.

When you return this code, you are certifying that you received the request and validated its signature.

401 You received the request, but you were unable to validate the signature.
500 You encountered an internal error.
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments