webhook.md

V2 Webook Documentation

Whenever a message is sent to or from a TextUs account we POST that message to your provided webhook URLs. The body of that request will contain:

{
  "timestamp":1500000000,
  "web_hook":{
    "id":1,
    "url":"http://httpbin.org/post",
    "account_id":1,
    "version":"2",
    "created_at":"2017-07-14T19:38:44.231Z",
    "updated_at":"2017-07-14T19:38:44.231Z"
  },
  "message":{
    "content":"Hello, Bart.",
    "read":false,
    "broadcast_id":null,
    "status":"created",
    "deliver_at":"2017-07-18T21:01:11.596Z",
    "from_autoresponse":null,
    "id":6,
    "created_at":"2017-07-18T21:01:11.596Z",
    "updated_at":"2017-07-18T21:01:11.596Z",
    "sender_id":6,
    "receiver_id":6,
    "sender_type":"User",
    "receiver_type":"Contact",
    "sender_phone":"+12230000028",
    "sender_name":"Sideshow Bob",
    "receiver_phone":"+12230000030",
    "receiver_name":"Bart Simpson",
    "image_url":null,
    "thumb_url":null
  }
}

Signature Verification (Optional)

Once you have a URL configured to accept inbound webhook messages, what's to prevent someone else from posing as TextUs and sending messages to your webhook?

Our V2 webhook implementation adds request signing so you can verify the authenticity of inbound webhook requests.

This verification is completely optional on your part. The signature will be contained in an X-TextUs-Signature header. To verify the signature, you would:

1. Parse the request body to retrieve the top-level timestamp field.
2. Extract the signature from the header.
3. Prepare the signed payload. This is achieved by combining the timestamp, a . character, and the request body.
4. Determine the expected signature value. Compute a HMAC with the SHA256 hash function, using your webhook's signing secret as the key and the signed payload string as the message.
5. Compare your computed signature with the value included in the X-TextUs-Signature field. If they match then you can be sure the request is authentic. In other words, OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), secret_key, timestamp + '.' + request_body) == X-TextUs-Signature