Webhooks are "user-defined HTTP callbacks". Once configured with your URL we will send an HTTP request to your endpoint every time a new message is sent or received within TextUs.

Whenever a message is sent to or from a TextUs account we POST that message to your provided Webhook's URL. The request will have a content type of Content-Type: application/vnd.textus-v2+json .

The body of that request will look something like this:

{
  "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
Did this answer your question?