Webhooks

Webhooks are a system of automated notifications indicating that an event has occurred in the EZ Texting system. Rather than requiring you to pull information via our API, webhooks push information to your destination when important events occur. Resource notifications are delivered via HTTP POST to a destination endpoint on your server and are sent based on the events you choose (see Webhooks). We recommend using SSL for webhook endpoints.

List of resources and events supporting webhooks:

inbound_text.received keyword.opt_in

After you verify your listener, subscribe it to either or both events. Finally, monitor the notifications that your listener receives when events occur.

JSON webhook postback example, for an inbound text received

{
"id":"123",
"type": "inbound_text.received",
"fromNumber:"14243798239",
"toNumber":"14243798231",
"message":"test message",
"received":"2020-03-06T10:31:18.724Z",
"optIn": false,
"optOut": false
}

JSON webhook postback example, for a keyword opt-in

{
"id":"123", 
"type": "keyword.opt_in",
"fromNumber:"14243798239",
"toNumber:"313131",
"keyword":"TESTKEY",
"received":"2020-03-06T10:31:18.724Z"
}

Authenticating Webhook Requests

EZ Texting webhooks can optionally include a secret token that, if included, is used as a secret key to create a HmacSHA1 hash of the JSON payload, returned in an 'X-Signature' header. This header can then be used to verify the callback POST is coming from EZ Texting. Note that verification via IP whitelisting is not feasible, as our system is based on a dynamic cloud infrastructure so the IP addresses of our servers may change dynamically without notice.

Verifying Request Signature

import java.security.SignatureException;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

import org.apache.commons.codec.binary.Base64;

public class ApiRequestVerifier {

    public String getHmacSignature(String data, String key) throws SignatureException {
        String result;
        SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), "HmacSHA1");
        Mac mac;
        try {
            mac = Mac.getInstance("HmacSHA1");
            mac.init(signingKey);
            byte[] rawHmac = mac.doFinal(data.getBytes());
            result = Base64.encodeBase64String(rawHmac).trim();
        } catch (Exception e) {
            throw new SignatureException("Failed to generate HMAC : " + e.getMessage());
        }
        return result;
    }
}

// then check signature in listener code
// String data = "{\"name\":\"test webhook\", \"callback\":\"sms:eztexting\"}";
// String secret = "mysecrets"; 
// Assert.assertEquals("v14pF7d5C1+CHNIEWlg+sw9v0Xg=", new ApiRequestVerifier().getHmacSignature(data, secret));