Handling Webhooks...

A webhook (sometimes called a web callback or HTTP push API) is how the HorizonWebRef.com system can provide your developer API application with real-time information. Webhooks will deliver data to your developer API applications as it happens, meaning you get data immediately, unlike with our typical API, where you would need to poll for data very frequently in order to get it real-time. This makes webhooks much more efficient.  Our webhooks will make an HTTP POST request to your webhook URL that you provide in your Developer Settings, and you will then be tasked with interpreting it.

Webhook Format

Webhooks are sent as HTTP POST requests with a JSON encoded body string.

Webhook Security

Webhooks deliver data to publicly available URLs in your app so there’s the chance that someone else could find that URL and then provide you with false data and/or spam your application. To prevent this from happening, we employ two techniques that will secure your application data. The first method is that all webhooks must use a secure HTTPS connection.  The second method, relies on you to verify the signature we provide in the header of all webhook requests.  All valid webhooks will contain a X-HWR-SIGNATURE header that will contain a hashed string which you can use to validate the source of the webhook as a legitimate souce.

Here's an example on how to handle the webhook signature header in PHP:

  1. <?php

    $signature = $_SERVER['HTTP_X_HWR_SIGNATURE'];
    $payload = file_get_contents("php://input");
    $developerSecretKey = "insert_your_secret_key_here";
    $expectedSignature = hash_hmac("sha256",$payload,$developerSecretKey);

         //webhook is legit!

         $webhookObject = json_decode($payload);

         //do all your processing here!

         //bad webhook!
         //abort, abort, abort!
         header("HTTP/1.1 403 Forbidden");


Important Notes

  • Keep your developer secret key a SECRET.  Don't share your developer secret key with anyone... seriously.
  • Webhooks will listen for your HTTP STATUS CODE to determine if you have successfully handled the webhook.  If you provide a 200 response, the webhook will assume that everything is fine and will not try again.  Any other non-200 response code will mean that the webhook will try again later.  Webhooks will be sent no more than once every 15 minutes and will try a maximum of 10 attempts.  If your application fails after 10 attempts the webhook will be permanently aborted.
  • Webhooks can make a lot of requests, depending on how much activity is occurring.   If you have a high volume of activities occurring, webhooks may end up overloading your app. Make sure your application can handle the expected scale of your webhook.

Feedback and Knowledge Base