Home › Guides › Developers

How to verify webhook signatures with HMAC SHA-256 (Node.js and PHP)

By the OmegaAPI team · Updated 19 November 2026 · 6 min read

A webhook is a URL on your server that another service calls when something happens — a payment succeeds, a message arrives, an OTP is received. Because the URL is public, anyone who finds it could send fake events. A signature lets your server prove the request really came from the service.

How HMAC signatures work

  1. You and the service share a secret (your webhook secret). It is never sent in the request.
  2. For each webhook the service calculates HMAC-SHA256(secret, raw request body) and sends it in a header. The Omega Messaging Gateway uses X-Signature: sha256=<hex>.
  3. Your server calculates the same HMAC over the exact raw bytes it received and compares. If they match, the body was not forged or changed.

The two most common mistakes are hashing a re-encoded JSON object instead of the raw body, and comparing with == instead of a timing-safe comparison.

Node.js (Express)

const express = require('express');
const crypto = require('crypto');
const app = express();
const SECRET = process.env.OMEGA_WEBHOOK_SECRET;

// keep the raw body: do NOT use express.json() before this route
app.post('/omega-webhook', express.raw({ type: '*/*' }), (req, res) => {
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  const got = String(req.headers['x-signature'] || '');
  const ok = got.length === expected.length &&
             crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body.toString('utf8'));
  if (event.otp) console.log('OTP received:', event.otp, 'from', event.sender);
  res.sendStatus(200); // answer fast; do slow work in a queue
});
app.listen(3000);

PHP

<?php
$secret = getenv('OMEGA_WEBHOOK_SECRET');
$raw = file_get_contents('php://input');          // raw body, before any decoding
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
$got = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

if (!hash_equals($expected, $got)) {                // timing-safe compare
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
// e.g. save $event['body'], $event['sender'], $event['otp'] to your database
http_response_code(200);

Good webhook habits

  • Respond quickly (within a few seconds) with HTTP 200, then process in the background.
  • Be idempotent — the same event may arrive twice; ignore duplicates by storing an ID or timestamp.
  • Use HTTPS for the webhook URL.
  • Rotate the secret if it ever leaks, and keep it out of your Git repository.
  • Log failed signature checks — repeated failures mean someone is probing your endpoint.

Set your webhook URL with POST /api/v1/webhook or from the panel. See the API documentation for the event fields.

Frequently asked questions

Why does my signature never match?

Usually because the body was parsed and re-serialised before hashing. Hash the raw request bytes exactly as received, with the same secret, and compare the full "sha256=..." string.

Is comparing with == really a problem?

A normal string comparison can leak timing information. Use crypto.timingSafeEqual in Node.js or hash_equals in PHP.

More guides