WebHooks plugin allows you to send notifications to external scripts. It works by sending http requests with event data to url defined in your webhook.
The module does not require any further configuartion.
After activating the module you can navigate to Extras → WebHooks to manage your webhooks.
This configuration can be changed at any time.
Each request will include special headers that will allow you to validate it and with details about executed event and webhook
HB-Hook
- system ID for this webhook that sent this request
HB-Event
- event name eg. after_clientadded
HB-Timestamp
- timestamp of this request, used to validate requestsHB-Signature
- signature generated for request data and timestampRequest body will depend on selected content type.
{"firsname": "Joe", "lastname": "Doe"} |
firstname=Joe&lastname=Doe |
Each request is signed with your secret key, this allows you to validate that the events were sent by your HostBill installation, not by a third party.
Here are the steps required to validate request signature.
Step 1: Obtain timestamp and signature from response headers, the HB-Signature
header contains signature that you want to verify and HB-Timestamp
contains timestamp used to generate that signature.
Step 2: Prepare the payload
string by concatenating:
Step 3: Compute a HMAC with the SHA256 hash function. Use secret
as the key, and use the payload
string as the message.
Step 4: Compare the signature in the HB-Signature
header to the one computed in step 3. If it matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.
<?php $secret = ''; // paste your Secret here //fetch request body $data = file_get_contents('php://input'); $payload = $_SERVER["HTTP_HB_TIMESTAMP"] . $data; $signature = hash_hmac('sha256', $payload, $secret); //compare signature in header with the one computed above if($signature !== $_SERVER["HTTP_HB_SIGNATURE"]) die('invalid signature') // signature valid, verify timestamp if($_SERVER["HTTP_HB_TIMESTAMP"] < time() - 60) die('timestamp older than 60 sec') |
Note: Webhooks plugin helps you by showing sample code for each webhook you generate in webhook details.