⇠ Back to Dev HubSupport Center ›API Status ›Engineering Blog ›
API Reference

Webhook Authentication

Webhook Authentication

Onfleet uses HMAC (hash-based message authentication code) with the SHA-512 hash function for additional authentication.

The purpose of HMAC is to validate that the message is indeed coming from Onfleet System and not anywhere other sources that are trying to inject different results and ensuring the authenticity of the message.

By using the webhook secret obtained on the Onfleet dashboard, your webhook server should verify that the source of webhook requests are indeed coming from Onfleet and is associated with your organization.

The difference between this and Webhook Validation is that HMAC is used to authenticate the message payload and the value of the data, while validation is a simple handshake between your service and Onfleet to ensure that the connection is mutually agreed upon.

Each webhook request contains a signature from Onfleet in X-Onfleet-Signature header. To authenticate the webhook request received on your webhook server, you will need to validate against this header.

To validate against X-Onfleet-Signature, you will need to compare its value with an HMAC you have generated using the hexadecimal format of your webhook secrets and the full body of the webhook POST request in raw bytes. We have provided some coding examples in Python, JavaScript and PHP.

import hashlib, hmac, binascii

hash = hmac.new(binascii.a2b_hex(secret), body.encode('utf-8'), 'sha512').hexdigest()

# Compare hash with the received X-Onfleet-Signature in raw bytes

const crypto = require('crypto')
const secret_in_hex = Buffer.from(secret, 'hex');

const hash = crypto.createHmac('sha512', secret_in_hex)
  .update(body)
  .digest('hex')

// Compare hash with the received X-Onfleet-Signature in raw bytes

<?php
  
$hash = hash_hmac('sha512', $body, hex2bin($secret));

// Compare $hash with the received X-Onfleet-Signature in raw bytes
?>

Required Components

You will be required to have the following information in order to do the authenticate calculation:

  • Secret is located at the Configuration → API & Webhook → Show Secret
  • Secret is an key string in Hexadecimal

To do the calculation one must have:

  • Webhook Secret - hexadecimal string
  • body of the webhook payload - json payload string
  • X-Onfleet-Signature provided by the webhook as part of the HTTP header - string

The end results string after the HMAC calculation(built-in with most languages) in the examples should match the Signature when compared as strings.

📘

Signed vs. Unsigned

Different programming languages have different bit representations, and that should be taken into consideration when executing the hex to binary conversion. For example, C and Java are signed languages, while Python, JS, and PHP are unsigned languages.