Webhooks

HTTP headers

POST <your webhook URL>
Content-Type:           application/json
x-verdacert-event:      order.ready
x-verdacert-event-id:   evt_4f8c1b2a3d6e9a01234567ef
x-verdacert-signature:  t=1716480000,v1=4d7a5c…

Body

{
  "id":        "evt_4f8c1b2a3d6e9a01234567ef",
  "type":      "order.ready",
  "createdAt": "2026-05-22T18:00:00.000Z",
  "data": {
    "jobId":              "ord_8a3c1b…",
    "orderNumber":        "VC-2026-000142",
    "status":             "ready",
    "apiKeyId":           "ak_4d8e…",
    "externalEndUserId":  "user_42",
    "promisedDeliveryAt": "2026-05-23T18:00:00.000Z"
  }
}

Receiver semantics

• Respond 2xx fast (under 5 seconds). We treat anything outside 200–299 (and 410) as a failure and schedule a retry.
• 2xx = delivered, no retry. 410 Gone= “delete this subscription, stop retrying.” 5xx / timeout = retry per the schedule below.
• Process async.Acknowledge with 200 first, then do the actual work on a background job. Don't hold the connection open while you process.
• Deduplicate on x-verdacert-event-id. We try not to deliver duplicates, but at-least-once delivery means it's possible — especially around outages.

TypeScript / Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

const WEBHOOK_SECRET = process.env.VERDACERT_WEBHOOK_SECRET!;
const TOLERANCE_SECONDS = 5 * 60;

export function verifyVerdacertSignature(
  rawBody: string,           // The exact body bytes the request arrived with.
  signatureHeader: string,   // x-verdacert-signature
): { ok: true; timestamp: number } | { ok: false; reason: string } {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.trim().split("=") as [string, string]),
  );
  const t = Number(parts.t);
  const v1 = parts.v1;
  if (!Number.isFinite(t) || !v1) return { ok: false, reason: "malformed" };

  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) {
    return { ok: false, reason: "stale" };
  }

  const expected = createHmac("sha256", WEBHOOK_SECRET)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(v1, "hex");
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return { ok: false, reason: "bad_signature" };
  }
  return { ok: true, timestamp: t };
}

Next.js Route Handler

import { NextResponse, type NextRequest } from "next/server";
import { verifyVerdacertSignature } from "@/lib/verify-verdacert";

export async function POST(req: NextRequest) {
  // Read the body as text first — verification uses the exact bytes.
  const raw = await req.text();
  const sig = req.headers.get("x-verdacert-signature") ?? "";

  const v = verifyVerdacertSignature(raw, sig);
  if (!v.ok) {
    return new NextResponse(`invalid: ${v.reason}`, { status: 400 });
  }

  const event = JSON.parse(raw) as {
    id: string;
    type: string;
    data: { jobId: string; orderNumber: string; status: string };
  };

  // Dedup on event.id BEFORE doing work.
  // … your queue / handler …

  return NextResponse.json({ received: true });
}

Python (Flask / FastAPI)

import hmac, hashlib, os, time

WEBHOOK_SECRET = os.environ["VERDACERT_WEBHOOK_SECRET"]
TOLERANCE = 5 * 60

def verify_verdacert_signature(raw_body: bytes, sig_header: str) -> bool:
    parts = dict(p.strip().split("=", 1) for p in sig_header.split(","))
    t = int(parts.get("t", "0"))
    v1 = parts.get("v1", "")

    if abs(time.time() - t) > TOLERANCE:
        return False

    expected = hmac.new(
        WEBHOOK_SECRET.encode("utf-8"),
        f"{t}.{raw_body.decode('utf-8')}".encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, v1)

Go

package verdacert

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "strconv"
    "strings"
    "time"
)

const tolerance = 5 * time.Minute

func VerifySignature(secret, sigHeader string, rawBody []byte) error {
    var t int64
    var v1 string
    for _, p := range strings.Split(sigHeader, ",") {
        kv := strings.SplitN(strings.TrimSpace(p), "=", 2)
        if len(kv) != 2 { continue }
        switch kv[0] {
        case "t":
            t, _ = strconv.ParseInt(kv[1], 10, 64)
        case "v1":
            v1 = kv[1]
        }
    }
    if t == 0 || v1 == "" {
        return fmt.Errorf("malformed signature header")
    }
    skew := time.Since(time.Unix(t, 0))
    if skew < 0 { skew = -skew }
    if skew > tolerance {
        return fmt.Errorf("stale event")
    }

    mac := hmac.New(sha256.New, []byte(secret))
    fmt.Fprintf(mac, "%d.%s", t, rawBody)
    expected := hex.EncodeToString(mac.Sum(nil))
    if !hmac.Equal([]byte(expected), []byte(v1)) {
        return fmt.Errorf("bad signature")
    }
    return nil
}

Ruby (Rails / Sinatra)

require "openssl"

WEBHOOK_SECRET = ENV.fetch("VERDACERT_WEBHOOK_SECRET")
TOLERANCE_SECONDS = 5 * 60

# raw_body must be the EXACT bytes from request.body.read.
# In Rails: `request.raw_post`. Don't use `params` — it'll re-serialize.
def verify_verdacert_signature(raw_body, sig_header)
  parts = sig_header.to_s.split(",").map { |p| p.strip.split("=", 2) }.to_h
  t  = parts["t"].to_i
  v1 = parts["v1"].to_s
  return false if t.zero? || v1.empty?
  return false if (Time.now.to_i - t).abs > TOLERANCE_SECONDS

  expected = OpenSSL::HMAC.hexdigest("SHA256", WEBHOOK_SECRET, "#{t}.#{raw_body}")
  # secure_compare is constant-time.
  OpenSSL.fixed_length_secure_compare(expected, v1)
rescue ArgumentError
  false   # length mismatch ⇒ fixed_length_secure_compare raises
end

# Rails controller
class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def verdacert
    raw = request.raw_post
    sig = request.headers["x-verdacert-signature"]
    return head :bad_request unless verify_verdacert_signature(raw, sig)

    event = JSON.parse(raw)
    # Dedup on event["id"] BEFORE enqueueing work.
    head :ok
  end
end

PHP (Laravel / vanilla)

<?php
// Always read the raw body for HMAC. Frameworks that pre-parse JSON
// reorder keys and break the signature.
$secret = getenv('VERDACERT_WEBHOOK_SECRET');
$tolerance = 5 * 60;

function verifyVerdacertSignature(string $rawBody, string $sigHeader, string $secret, int $tolerance = 300): bool {
    $parts = [];
    foreach (explode(',', $sigHeader) as $p) {
        [$k, $v] = array_pad(explode('=', trim($p), 2), 2, null);
        if ($k !== null) $parts[$k] = $v;
    }
    $t  = (int)($parts['t'] ?? 0);
    $v1 = (string)($parts['v1'] ?? '');
    if ($t === 0 || $v1 === '') return false;
    if (abs(time() - $t) > $tolerance) return false;

    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    // hash_equals is constant-time.
    return hash_equals($expected, $v1);
}

// Laravel controller
class VerdacertWebhookController extends Controller {
    public function __invoke(\Illuminate\Http\Request $request) {
        $raw = $request->getContent();
        $sig = $request->header('x-verdacert-signature') ?? '';
        if (!verifyVerdacertSignature($raw, $sig, env('VERDACERT_WEBHOOK_SECRET'))) {
            return response('bad signature', 400);
        }
        $event = json_decode($raw, true);
        // Dedup on $event['id'] BEFORE enqueueing work.
        return response()->json(['received' => true]);
    }
}