Skip to main content

SendHub WebHooks

Branden Williams
  • Updated

In order to enable the webhooks feature, login to your SendHub application, browse to the My Settings page and enter a valid URL in the WebHook URL textbox as shown in the image below. When you enter the URL, it automatically sends a test webhook to the URL you entered.


Supported WebHooks

Currently, SendHub will send seven types of webhooks:
● Received Message: Sent when a user receives an inbound message
● Received Block: Sent when a user is blocked (by a contact texting STOP)
● Received Unblock: Sent when a user is unblocked (by a contact texting START)
● Received Subscription: Sent when a contact subscribes to a group
● Received Confirmed: Sent when a contact confirms their subscription to a group
● Received Unsubscribe: Sent when a contact unsubscribes from a group
● Test: Sent when a user initiates a webhook test (via the settings page)

All webhook data is sent as JSON within the body of a POST request to the configured URL.

Authentication

Validating Requests are coming from SendHub

If your application exposes sensitive data, or is possibly mutative to your data, then you may want to be sure that the HTTP requests to your web application are indeed coming from SendHub, and not a malicious third party. To allow you this level of security, SendHub cryptographically signs its requests. Here's how it works:

  1. Turn on SSL on your server and configure your webhook url to use HTTPS.
  2. SendHub appends the JSON body to the full URL.
  3. SendHub takes the resulting string (the full URL and the JSON body) and signs it using HMAC-SHA1 and your API Key as the key.
  4. SendHub sends this signature in an HTTP header called X-SendHub-Signature

Then, on your end, if you want to verify the authenticity of the request, you can reassemble the data string by going through the exact same process. If our two hashes match, then the request was authentic. You can then be sure that all the data used to construct the hash, including the full URL and JSON data were all sent to you by SendHub. Here's how you would perform the validation on your end:

  1. Take the full URL of the request URL.
  2. If the request is a POST, sort all of the POST parameters alphabetically (using Unix-style case-sensitive sorting order).
  3. Append the full URL and the body of the request.
  4. Sign the resulting string with HMAC-SHA1 using your API Key as the key.
  5. Base64 encode the resulting hash value.
  6. Compare your hash to ours, submitted in the X-SendHub-Signature header. If they match, then you're good to go.

Error Handling

SendHub will attempt to send a webhook a maximum of two times for each instance of a message. If the message is unable to be sent, for any reason, SendHub will send the user an email (if configured in the account) indicating a webhook failed and the reason.