Verify webhook signatures in Node, Python or PHP

Anyone who learns your endpoint's address could send it fake events. The signature proves an event came from Hushdesk. Check it on every request before you act on the event.

Before you start

• Who this is for: developers running a webhook endpoint.
• Plan: all plans.
• What you need: the signing secret you typed when connecting the Webhooks app, stored in your server's environment (for example HUSHDESK_WEBHOOK_SECRET).

Step by step

1. Read the raw request body as bytes. Do not parse it yet.
2. Compute HMAC-SHA256(secret, rawBody) as lowercase hex and add sha256= in front.
3. Compare it with the X-Hushdesk-Signature header using a constant-time comparison.
4. If they match, parse the JSON and handle the event. If not, answer 401.
5. Answer 200 quickly, then do slow work in the background.

Node.js (Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();
app.post('/helpdesk-events', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.HUSHDESK_WEBHOOK_SECRET).update(req.body).digest('hex');
  const got = req.get('X-Hushdesk-Signature') || '';
  const ok = got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
  if (!ok) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(200);
  // handle event.event and event.ticket here
});

Python (Flask)

import hashlib, hmac, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/helpdesk-events")
def helpdesk_events():
    raw = request.get_data()
    expected = "sha256=" + hmac.new(os.environ["HUSHDESK_WEBHOOK_SECRET"].encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(request.headers.get("X-Hushdesk-Signature", ""), expected):
        abort(401)
    event = request.get_json()
    return "", 200

PHP

<?php
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('HUSHDESK_WEBHOOK_SECRET'));
$got = $_SERVER['HTTP_X_HUSHDESK_SIGNATURE'] ?? '';
if (!hash_equals($expected, $got)) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
http_response_code(200);

What happens next

Your endpoint only acts on genuine Hushdesk events. The Webhooks card in Hushdesk shows Last delivery as delivered when your endpoint answers 2xx, or failed with the status code when it does not.

Tips

• Keep the secret out of your code repository. Use environment variables.
• When you change the secret in Hushdesk with Update and test, deploy the new secret to your endpoint at the same time, or the test will fail.
• Use the X-Hushdesk-Event header to route events before parsing the body.

Troubleshooting

"Your endpoint did not answer the test event with a 2xx"

Your code rejected the test ping, often because the signature was computed over a parsed body. Use the raw body.

"Use a signing secret of at least 16 characters"

Choose a longer secret before connecting.