onfleet-webhooks

Onfleet Webhooks

Onfleet is a last-mile delivery platform. Each Onfleet webhook targets one trigger (task started, task completed, worker on duty, and so on). When you create a webhook, Onfleet first sends an unsigned GET ?check=<random_string> request to validate the URL. After that, every event arrives as a signed POST with an X-Onfleet-Signature header.

When to Use This Skill

• How do I receive Onfleet webhooks?
• Why won't Onfleet save my webhook URL? (the GET ?check= handshake)
• How do I verify the X-Onfleet-Signature header?
• Why does my Onfleet signature never match? (the secret is hex)
• How do I handle taskCompleted, taskFailed, taskEta or workerDuty?

Validation Handshake

When a webhook is created, Onfleet sends GET <your url>?check=<random_string>. Reply 200 with the exact string as a plain-text body. Onfleet doesn't accept a 204, and the request is not signed, so don't run signature verification on it. The string changes on every attempt.

app.get('/webhooks/onfleet', (req, res) => {
  const check = req.query.check;
  if (typeof check !== 'string') {
    return res.status(400).type('text/plain').send('Missing check parameter');
  }
  res.status(200).type('text/plain').send(check);
});

Signature Verification (core)

Header	X-Onfleet-Signature
Algorithm	HMAC-SHA512, hex digest
Key	The organisation's webhook secret, hex-decoded to bytes
Signed content	The raw request body bytes. No timestamp, no prefix

The secret is a hex string. Use it as an HMAC key only after hex-decoding it. If you pass the string as-is, you get a well-formed digest that never matches.

const crypto = require('crypto');

function verifyOnfleetSignature(rawBody, signatureHeader, secretHex) {
  if (!signatureHeader) {
    return { valid: false, error: 'Missing X-Onfleet-Signature header' };
  }

  const expected = crypto
    .createHmac('sha512', Buffer.from(secretHex, 'hex'))
    .update(rawBody)
    .digest('hex');

  const received = Buffer.from(signatureHeader.trim().toLowerCase(), 'utf8');
  const computed = Buffer.from(expected, 'utf8');

  // timingSafeEqual throws on unequal lengths, so check first.
  if (received.length !== computed.length) {
    return { valid: false, error: 'Invalid signature' };
  }
  if (!crypto.timingSafeEqual(received, computed)) {
    return { valid: false, error: 'Invalid signature' };
  }
  return { valid: true };
}