Courier Invoice

Web Hooks


A webhook is an array with two keys sent as a json encoded string using the php function json_encode() with no options set.

Each webhook has the key X-CI-AUTH in the header that contains a validation token that can be used to ensure that the webhook was indeed sent by courierinvoice. The token is a hash of the webhook, your account number, and the time value included in the webhook using your Private API Key.
$token = hash_hmac('sha256', $webhook . 'Your_Account_Number' . $timeVal, $privateKey);
The token should be regenerated in similar fashion and tested using the function hash_equals()

Retreived token:
$token = $_SERVER['HTTP_X_CI_AUTH'] ?? bin2hex(random_bytes(1e4));
$headers = array_change_key_case(getallheaders(), CASE_UPPER);
$token = $headers['X-CI-AUTH'] ?? bin2hex(random_bytes(1e4));

To help prevent sending redundant webhooks, a webhook is created based first upon the type of request made to the API, then by what information is in the database and what information is sent with the request. For example, a PUT request to update an oncall ticket that has been picked up would include the data key "pTimeStamp" and, optionally, "Notes". A call to the database determines if the ticket is contract or on call. If only the one or two values are present the timestamp key will determine what step to include in the webhook. This example would result in a webhook of "ticket.oncall.pickup". If the ticket already had a value in the database for "pTimeStamp" or more values are sent then the webhook would be "ticket.oncall.update". If multiple timestamp keys are included in a request they are tested in reverse order (d2TimeStamp, dTimeStamp, pTimeStamp, DispatchTimeStamp, ReceivedDate) and the first key encountered determines which webhook is to be sent. If the call includes the TransferState key all timestamps are ignored and a transfer webhook is sent. So if a ticket is received and dispatched in the same call to the API only the dispatch webhook would be sent. If multiple resources are created / updated / deleted with a single call to the API then the Data array will contain a webhook for each resource.