Webhook signature verification

Webhooks are the moments where external trust meets our money-moving code. A forged webhook that bypassed verification could fake a payment. None of them do. This page is the per-source verification spec.

The verification stack

Three checks. Each rejects independently. A failure at any layer means the operation does not proceed.

OPay — three signature schemes

OPay fires webhooks with different signature header conventions depending on the event type. Our middleware accepts all three.

Scheme 1: `x-opay-encrypted-body` (full body)

Header present: x-opay-encrypted-body: <hex_signature>. Verification:

const expected = createHmac('sha512', OPAY_SECRET)
  .update(rawBody)
  .digest('hex');

if (!timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
  return res.status(401).end();
}

Scheme 2: `x-opay-encrypted-body` (DVA field subset)

Same header. But for dynamic-virtual-account events, the signature is computed over a three-field JSON subset:

const subset = JSON.stringify({
  transaction_reference: body.transaction_reference,
  amount_received: body.amount_received,
  merchant_reference: body.merchant_reference
});

const expected = createHmac('sha512', OPAY_SECRET)
  .update(subset)
  .digest('hex');

We try the full-body scheme first; if it fails, we fall back to the DVA subset.

Scheme 3: `x-opay-signature` (v2/v3)

A different header, used for newer event types. Two sub-modes:

// v2: full body
const expected1 = createHmac('sha512', OPAY_SECRET)
  .update(rawBody)
  .digest('hex');

// v3: pipe-delimited field concat
const fields = [body.event, body.transaction_reference, body.amount, body.timestamp];
const expected2 = createHmac('sha512', OPAY_SECRET)
  .update(fields.join('|'))
  .digest('hex');

if (
  !timingSafeEqual(Buffer.from(expected1), Buffer.from(signature)) &&
  !timingSafeEqual(Buffer.from(expected2), Buffer.from(signature))
) {
  return res.status(401).end();
}

The middleware logic

async function verifyOPayWebhook(req: Request, res: Response, next: NextFunction) {
  const encryptedHeader = req.header('x-opay-encrypted-body');
  const signatureHeader = req.header('x-opay-signature');
  const rawBody = req.rawBody as Buffer;

  if (encryptedHeader) {
    // Try full body
    if (timingSafeEqual(hmacSha512(OPAY_SECRET, rawBody), Buffer.from(encryptedHeader, 'hex'))) {
      return next();
    }
    // Try DVA subset
    const subset = jsonSubset(JSON.parse(rawBody.toString()));
    if (timingSafeEqual(hmacSha512(OPAY_SECRET, subset), Buffer.from(encryptedHeader, 'hex'))) {
      return next();
    }
  }

  if (signatureHeader) {
    // Try full body
    if (timingSafeEqual(hmacSha512(OPAY_SECRET, rawBody), Buffer.from(signatureHeader, 'hex'))) {
      return next();
    }
    // Try pipe-delimited fallback
    const fields = pipeFields(JSON.parse(rawBody.toString()));
    if (timingSafeEqual(hmacSha512(OPAY_SECRET, fields), Buffer.from(signatureHeader, 'hex'))) {
      return next();
    }
  }

  audit.write({ kind: 'webhook_signature_rejected', source: 'opay', headers: req.headers });
  return res.status(401).end();
}

The reconcile guard

After signature verification passes, every credit-bearing event triggers a second check: re-verification against OPay’s authoritative transaction-verify endpoint.

async function reconcileWebhook(webhook: OPayChargeSuccessful) {
  const verification = await opayClient.verifyTransaction(webhook.transaction_reference);

  if (!/success/i.test(verification.status)) {
    audit.write({ kind: 'webhook_rejected_status_mismatch', ...webhook });
    return false;
  }

  if (BigInt(verification.amount_kobo) !== BigInt(webhook.amount_kobo)) {
    audit.write({ kind: 'webhook_rejected_amount_mismatch', ...webhook });
    return false;
  }

  return true; // safe to credit
}

A forged webhook with a stolen secret would pass the HMAC check. It would fail the reconcile check because OPay’s own database would not show a successful transaction with that reference.

Meta WhatsApp Cloud

Meta uses X-Hub-Signature-256, the standard HMAC-SHA256 webhook signature shape used across Facebook/Instagram/WhatsApp.

async function verifyWhatsAppWebhook(req: Request, res: Response, next: NextFunction) {
  const signatureHeader = req.header('x-hub-signature-256') || '';
  // header format: "sha256=<hex>"
  const signature = signatureHeader.replace(/^sha256=/, '');
  const expected = createHmac('sha256', META_APP_SECRET)
    .update(req.rawBody as Buffer)
    .digest('hex');

  if (!timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    audit.write({ kind: 'webhook_signature_rejected', source: 'whatsapp' });
    return res.status(401).end();
  }

  next();
}

The Meta webhook also requires hub-verification during initial setup: a GET /webhook request from Meta with hub.mode=subscribe, hub.verify_token=<our_token>, hub.challenge=<random>. We echo back hub.challenge to complete setup. After setup, only POST /webhook traffic flows.

Voice runtime webhooks

Our voice runtime uses a shared-secret header:

async function verifyVoiceWebhook(req: Request, res: Response, next: NextFunction) {
  const headerSecret = req.header('x-voice-secret');
  if (!headerSecret || !timingSafeEqual(Buffer.from(headerSecret), Buffer.from(VOICE_SECRET))) {
    audit.write({ kind: 'webhook_signature_rejected', source: 'voice' });
    return res.status(401).end();
  }
  next();
}

Simpler than HMAC because the body shape varies and pre-shared secret comparison is sufficient for our trust relationship with the runtime. Timing-safe compare is still used.

SMS gateway webhooks

Our Go SMS gateway signs inbound webhooks (replies) with a shared secret over the raw body:

async function verifyGatewaySmsWebhook(req: Request, res: Response, next: NextFunction) {
  const signature = req.header('x-sms-gateway-signature');
  const expected = createHmac('sha256', SMS_GATEWAY_SECRET)
    .update(req.rawBody as Buffer)
    .digest('hex');

  if (!timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    audit.write({ kind: 'webhook_signature_rejected', source: 'sms-gateway' });
    return res.status(401).end();
  }

  next();
}

Partner API outbound webhooks

When Guild fires a webhook to a partner’s endpoint (consent.granted, standing.tier_changed, etc.), we sign the outbound with the partner’s per-subscription secret. Each partner verifies on receipt with the same shape.

function signPartnerWebhook(payload: object, secret: string): { signature: string; timestamp: number } {
  const timestamp = Math.floor(Date.now() / 1000);
  const body = JSON.stringify(payload);
  const signature = createHmac('sha256', secret)
    .update(`${timestamp}.${body}`)
    .digest('hex');
  return { signature, timestamp };
}

We include the timestamp in the signed material to support replay protection on the partner’s side. Partners are expected to reject events with timestamps more than 5 minutes off from their server time. Full partner-side verification spec: Partner webhooks.

Verifying in your language

Copy-paste-ready reference implementations of the partner-side signature check. Same logic across all five:

Pull the X-Guild-Signature header (t=<unix_seconds>,v1=<hex_hmac>).
Reject if the timestamp drifts more than 300 seconds from your server clock.
Compute HMAC-SHA256 of {timestamp}.{raw_body} with your webhook secret.
Compare against v1 in constant time.
Only process the event if all four pass.

More language samples on the way — these five (JavaScript, Python, PHP, C#, Java) cover most partner stacks today.

import crypto from 'node:crypto';

/**
 * Verify a Guild webhook signature.
 *
 * @param {string} signatureHeader - the X-Guild-Signature header value
 * @param {string|Buffer} rawBody - the raw request body (bytes, not parsed JSON)
 * @param {string} secret - the webhook subscription secret (whsec_...)
 * @returns {boolean} true if the signature is valid and the timestamp is fresh
 */
export function verifyGuildWebhook(signatureHeader, rawBody, secret) {
  if (!signatureHeader || typeof signatureHeader !== 'string') {
    return false;
  }

  const parts = Object.fromEntries(
    signatureHeader.split(',').map((p) => p.split('=', 2))
  );
  const t = parseInt(parts.t, 10);
  const v1 = parts.v1;

  if (!t || !v1) return false;

  // Reject events older than 5 minutes (replay protection)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - t) > 300) return false;

  const body = Buffer.isBuffer(rawBody) ? rawBody.toString('utf8') : rawBody;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${body}`)
    .digest('hex');

  try {
    return crypto.timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(v1, 'hex')
    );
  } catch {
    return false;
  }
}

// Express usage:
//   app.post('/webhooks/guild',
//     express.raw({ type: 'application/json' }),
//     (req, res) => {
//       const ok = verifyGuildWebhook(
//         req.header('X-Guild-Signature'),
//         req.body,
//         process.env.GUILD_WEBHOOK_SECRET
//       );
//       if (!ok) return res.status(401).end();
//       const event = JSON.parse(req.body.toString('utf8'));
//       // ... handle event ...
//       res.status(200).end();
//     });

import hmac
import hashlib
import time


def verify_guild_webhook(signature_header: str, raw_body: bytes, secret: str) -> bool:
    """
    Verify a Guild webhook signature.

    Args:
        signature_header: the X-Guild-Signature header value
        raw_body: the raw request body (bytes, not parsed JSON)
        secret: the webhook subscription secret (whsec_...)

    Returns:
        True if the signature is valid and the timestamp is fresh.
    """
    if not signature_header:
        return False

    try:
        parts = dict(pair.split("=", 1) for pair in signature_header.split(","))
        t = int(parts["t"])
        v1 = parts["v1"]
    except (ValueError, KeyError):
        return False

    # Reject events older than 5 minutes (replay protection)
    if abs(time.time() - t) > 300:
        return False

    signed = f"{t}.".encode("utf-8") + raw_body
    expected = hmac.new(
        secret.encode("utf-8"),
        signed,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, v1)


# Flask usage:
#   @app.post("/webhooks/guild")
#   def guild_webhook():
#       ok = verify_guild_webhook(
#           request.headers.get("X-Guild-Signature", ""),
#           request.get_data(),  # raw bytes
#           os.environ["GUILD_WEBHOOK_SECRET"],
#       )
#       if not ok:
#           abort(401)
#       event = request.get_json()
#       # ... handle event ...
#       return "", 200

<?php

/**
 * Verify a Guild webhook signature.
 *
 * @param string|null $signatureHeader The X-Guild-Signature header value
 * @param string      $rawBody         The raw request body (not json_decoded)
 * @param string      $secret          The webhook subscription secret (whsec_...)
 * @return bool                        True if signature is valid and timestamp is fresh
 */
function verifyGuildWebhook(?string $signatureHeader, string $rawBody, string $secret): bool
{
    if (empty($signatureHeader)) {
        return false;
    }

    $parts = [];
    foreach (explode(',', $signatureHeader) as $pair) {
        $kv = explode('=', $pair, 2);
        if (count($kv) === 2) {
            $parts[$kv[0]] = $kv[1];
        }
    }

    if (!isset($parts['t'], $parts['v1'])) {
        return false;
    }

    $timestamp = (int) $parts['t'];
    $providedSig = $parts['v1'];

    // Reject events older than 5 minutes (replay protection)
    if (abs(time() - $timestamp) > 300) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

    return hash_equals($expected, $providedSig);
}

// Plain PHP / Laravel usage:
//   $raw = file_get_contents('php://input');
//   $sig = $_SERVER['HTTP_X_GUILD_SIGNATURE'] ?? null;
//   if (!verifyGuildWebhook($sig, $raw, getenv('GUILD_WEBHOOK_SECRET'))) {
//       http_response_code(401);
//       exit;
//   }
//   $event = json_decode($raw, true);
//   // ... handle event ...
//   http_response_code(200);

using System;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Text;

public static class GuildWebhookVerifier
{
    /// <summary>
    /// Verify a Guild webhook signature.
    /// </summary>
    /// <param name="signatureHeader">The X-Guild-Signature header value.</param>
    /// <param name="rawBody">The raw request body string (not parsed JSON).</param>
    /// <param name="secret">The webhook subscription secret (whsec_...).</param>
    /// <returns>True if the signature is valid and the timestamp is fresh.</returns>
    public static bool Verify(string? signatureHeader, string rawBody, string secret)
    {
        if (string.IsNullOrEmpty(signatureHeader))
            return false;

        var parts = new Dictionary<string, string>();
        foreach (var pair in signatureHeader.Split(','))
        {
            var kv = pair.Split('=', 2);
            if (kv.Length == 2)
                parts[kv[0]] = kv[1];
        }

        if (!parts.TryGetValue("t", out var tString) ||
            !parts.TryGetValue("v1", out var provided) ||
            !long.TryParse(tString, out var timestamp))
        {
            return false;
        }

        // Reject events older than 5 minutes (replay protection)
        var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
        if (Math.Abs(now - timestamp) > 300)
            return false;

        var signed = $"{timestamp}.{rawBody}";
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(signed));
        var expected = Convert.ToHexString(hash).ToLowerInvariant();

        return CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(expected),
            Encoding.UTF8.GetBytes(provided)
        );
    }
}

// ASP.NET Core usage:
//   [HttpPost("/webhooks/guild")]
//   public async Task<IActionResult> GuildWebhook()
//   {
//       Request.EnableBuffering();
//       using var reader = new StreamReader(Request.Body);
//       var raw = await reader.ReadToEndAsync();
//       var sig = Request.Headers["X-Guild-Signature"].ToString();
//       if (!GuildWebhookVerifier.Verify(sig, raw, _config["GuildWebhookSecret"]))
//           return Unauthorized();
//       var evt = JsonSerializer.Deserialize<GuildEvent>(raw);
//       // ... handle event ...
//       return Ok();
//   }

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HashMap;
import java.util.Map;

public final class GuildWebhookVerifier {

    private GuildWebhookVerifier() {}

    /**
     * Verify a Guild webhook signature.
     *
     * @param signatureHeader the X-Guild-Signature header value
     * @param rawBody         the raw request body (not parsed JSON)
     * @param secret          the webhook subscription secret (whsec_...)
     * @return true if the signature is valid and the timestamp is fresh
     */
    public static boolean verify(String signatureHeader, String rawBody, String secret) {
        if (signatureHeader == null || signatureHeader.isEmpty()) {
            return false;
        }

        Map<String, String> parts = new HashMap<>();
        for (String pair : signatureHeader.split(",")) {
            String[] kv = pair.split("=", 2);
            if (kv.length == 2) {
                parts.put(kv[0], kv[1]);
            }
        }

        String tString = parts.get("t");
        String provided = parts.get("v1");
        if (tString == null || provided == null) {
            return false;
        }

        long timestamp;
        try {
            timestamp = Long.parseLong(tString);
        } catch (NumberFormatException e) {
            return false;
        }

        // Reject events older than 5 minutes (replay protection)
        long now = System.currentTimeMillis() / 1000L;
        if (Math.abs(now - timestamp) > 300) {
            return false;
        }

        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(
                secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
            byte[] hash = mac.doFinal(
                (timestamp + "." + rawBody).getBytes(StandardCharsets.UTF_8));

            StringBuilder hex = new StringBuilder(hash.length * 2);
            for (byte b : hash) {
                hex.append(String.format("%02x", b));
            }

            return MessageDigest.isEqual(
                hex.toString().getBytes(StandardCharsets.UTF_8),
                provided.getBytes(StandardCharsets.UTF_8)
            );
        } catch (Exception e) {
            return false;
        }
    }
}

// Spring Boot usage:
//   @PostMapping("/webhooks/guild")
//   public ResponseEntity<Void> guildWebhook(
//           @RequestHeader("X-Guild-Signature") String sig,
//           @RequestBody String rawBody) {
//       if (!GuildWebhookVerifier.verify(sig, rawBody, webhookSecret)) {
//           return ResponseEntity.status(401).build();
//       }
//       GuildEvent event = objectMapper.readValue(rawBody, GuildEvent.class);
//       // ... handle event ...
//       return ResponseEntity.ok().build();
//   }

Three things every reference implementation gets right that hand-rolled code often misses:

Use the raw body, not a re-serialised JSON string. If you parse the body and then JSON.stringify it again, the bytes will differ from what we signed (whitespace, key order, etc.) and verification will fail. Most frameworks let you access the raw bytes — use them.
Constant-time compare. Don’t use == or === for the signature check. Use your language’s hmac.compare_digest / timingSafeEqual / MessageDigest.isEqual / hash_equals / FixedTimeEquals. Linear-time string comparison leaks information about how close a wrong signature was to right.
Reject stale timestamps. Replay protection is half of the security guarantee. Without the timestamp check, a captured webhook from a year ago could be replayed against your handler today.

Why raw body matters

nginx is configured with proxy_request_buffering off on every webhook route. If nginx buffered and re-emitted the body, the byte sequence could change (different whitespace, different line endings, etc.) and HMAC verification would fail. express.raw() middleware is used on webhook routes to expose the unmodified body bytes as req.rawBody. Standard express.json() parsing happens after signature verification, never before. This is one of those quiet correctness details that only matters when it doesn’t work. We learned this from a real bug; the fix is one line in nginx.conf.

Idempotency on inbound webhooks

After signature verification, every webhook is idempotency-checked on its source-provided event ID. Detail in OPay reference. A duplicate delivery is acknowledged with 200 but does nothing. OPay’s own retry on a network hiccup never causes double-processing.

OPay reference

The full OPay webhook event taxonomy and reconcile guard logic.

Partner webhooks

The outbound side — signing webhooks we deliver to partners.

Audit ledger

Where webhook events end up.

Get Started

For Job Seekers

For Traders

For Employers

For Partners

Channels

Standing & the Ledger

Architecture

Security & Trust

Webhook signature verification

The verification stack

OPay — three signature schemes

Scheme 1: `x-opay-encrypted-body` (full body)

Scheme 2: `x-opay-encrypted-body` (DVA field subset)

Scheme 3: `x-opay-signature` (v2/v3)

The middleware logic

The reconcile guard

Meta WhatsApp Cloud

Voice runtime webhooks

SMS gateway webhooks

Partner API outbound webhooks

Verifying in your language

Why raw body matters

Idempotency on inbound webhooks

What to read next

OPay reference

Partner webhooks

Audit ledger

​The verification stack

​OPay — three signature schemes

​Scheme 1: x-opay-encrypted-body (full body)

​Scheme 2: x-opay-encrypted-body (DVA field subset)

​Scheme 3: x-opay-signature (v2/v3)

​The middleware logic

​The reconcile guard

​Meta WhatsApp Cloud

​Voice runtime webhooks

​SMS gateway webhooks

​Partner API outbound webhooks

​Verifying in your language

​Why raw body matters

​Idempotency on inbound webhooks

​What to read next

OPay reference

Partner webhooks

Audit ledger

The verification stack

OPay — three signature schemes

Scheme 1: `x-opay-encrypted-body` (full body)

Scheme 2: `x-opay-encrypted-body` (DVA field subset)

Scheme 3: `x-opay-signature` (v2/v3)

The middleware logic

The reconcile guard

Meta WhatsApp Cloud

Voice runtime webhooks

SMS gateway webhooks

Partner API outbound webhooks

Verifying in your language

Why raw body matters

Idempotency on inbound webhooks

What to read next