Webhooks

1. Overview

A webhook endpoint is an HTTPS URL you expose in your system. MatchAudit sends JSON POST requests to that URL whenever a subscribed event occurs.

• You configure endpoints in the Dashboard → Webhooks.
• Each endpoint has a signing secret you must store securely and use to verify incoming requests.
• Events are delivered at least once with automatic retries for non-2xx responses.

2. Event payload

Every webhook request contains a JSON body with a consistent envelope:

{
  "id": "evt_1234abcd-5678-90ef-...",
  "type": "screening.completed",
  "created": "2025-11-04T16:32:49.507Z",
  "version": "1",
  "data": {
    // Event-specific payload
  }
}

• id – globally unique event ID (UUID). Use this for idempotency in your system.
• type – event name (e.g. screening.completed, webhook.test).
• created – ISO-8601 timestamp when the event was created.
• version – payload schema version (currently "1").
• data – event-specific body (for example, the screening job and result summary).

3. Headers & signature

MatchAudit signs each webhook using an HMAC-SHA256 signature so you can verify the request really comes from us and hasn't been tampered with.

3.1 HTTP headers

For each outbound webhook we send:

POST /your/webhook/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: MatchAudit-Webhook/Dispatch/1.0

x-matchaudit-event-id: evt_1234abcd-5678-...
x-matchaudit-event-type: screening.completed
x-matchaudit-event-created: 2025-11-04T16:32:49.507Z
x-matchaudit-version: 1
x-matchaudit-signature: sha256=<hex-digest>

• x-matchaudit-event-id – same as id in the JSON body.
• x-matchaudit-event-type – same as type.
• x-matchaudit-event-created – same as created.
• x-matchaudit-version – payload schema version.
• x-matchaudit-signature – HMAC-SHA256 signature over the raw request body.

3.2 Signature format

The signature header is formatted as:

x-matchaudit-signature: sha256=<hex-digest>

Where <hex-digest> is:

HMAC_SHA256(secret = "whsec_...", payload = raw_request_body)

Important: compute the HMAC over the exact raw body string as received, before parsing JSON. The secret is the one you see once when creating or rotating a webhook endpoint in the dashboard.

4. Verifying webhooks

You should verify every webhook request before you trust it. The basic algorithm is:

1. Read the raw request body as a string.
2. Read the x-matchaudit-signature header.
3. Compute your own HMAC-SHA256 digest using your endpoint's signing secret and the raw body.
4. Compare using a constant-time comparison. If they match, accept the webhook.

4.1 Node / TypeScript example (Express)

import crypto from "crypto";
import type { Request, Response } from "express";

const MATCHAUDIT_SECRET = process.env.MATCHAUDIT_WEBHOOK_SECRET!;

function timingSafeEqual(a: string, b: string): boolean {
  const aBuf = Buffer.from(a, "utf8");
  const bBuf = Buffer.from(b, "utf8");
  if (aBuf.length !== bBuf.length) return false;
  return crypto.timingSafeEqual(aBuf, bBuf);
}

export function handleMatchAuditWebhook(req: Request, res: Response) {
  const rawBody = (req as any).rawBody?.toString("utf8") ?? JSON.stringify(req.body);
  const sigHeader = req.header("x-matchaudit-signature") || "";
  const expected = "sha256=" + crypto
    .createHmac("sha256", MATCHAUDIT_SECRET)
    .update(rawBody, "utf8")
    .digest("hex");

  if (!sigHeader || !timingSafeEqual(sigHeader, expected)) {
    return res.status(400).send("Invalid webhook signature");
  }

  const event = JSON.parse(rawBody);
  // TODO: handle event.type, event.data, etc.
  res.status(200).send("ok");
}

4.2 Python example (FastAPI)

import hmac
import hashlib
import os
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
SECRET = os.environ["MATCHAUDIT_WEBHOOK_SECRET"]

def verify_signature(raw_body: bytes, header: str | None) -> bool:
  if not header:
    return False
  if not header.startswith("sha256="):
    return False
  received = header[len("sha256=") :]
  digest = hmac.new(SECRET.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
  # constant-time compare
  return hmac.compare_digest(received, digest)

@app.post("/webhooks/matchaudit")
async def matchaudit_webhook(request: Request):
  raw = await request.body()
  sig = request.headers.get("x-matchaudit-signature")

  if not verify_signature(raw, sig):
    raise HTTPException(status_code=400, detail="Invalid signature")

  event = await request.json()
  # TODO: handle event["type"], event["data"], etc.
  return {"ok": True}

5. Retries & idempotency

5.1 When MatchAudit retries

For each delivery attempt, we look at your HTTP response:

• 2xx – considered success. We do not retry this delivery.
• Non-2xx or network error/timeout – considered failure. We retry up to a maximum number of attempts with backoff.

Retries are scheduled in the background; you don't need to do anything special other than return a 2xx status when you've safely persisted the event.

5.2 Handling at-least-once delivery

Webhooks are delivered on an at-least-once basis. This means you may occasionally see the same event more than once (for example, if your server returned a 500 on the first attempt).

To make processing idempotent, we recommend:

• Use event.id (also in x-matchaudit-event-id) as an idempotency key.
• Before processing a webhook, check whether you have already handled that event.id.
• If you already processed it, skip side effects but still return 200 OK.

6. Testing webhooks

6.1 Using the Dashboard test button

In the Dashboard → Webhooks section you can:

• Create an endpoint and copy the signing secret into your server.
• Use “Send test” to trigger a webhook.test event to your active endpoint.
• Inspect recent deliveries and attempts in the dashboard and correlate with your server logs.

6.2 One-off tests to a specific URL

The test UI also lets you provide an explicit URL (for example, a webhook.site URL). In that case we send a single test event directly to that URL without requiring a configured endpoint. This is useful to quickly see the payload and headers your server will receive.

6.3 Local development tips

• Use a tunneling tool like ngrok or Cloudflare Tunnel to expose your local server, then set that public URL as your webhook endpoint.
• Log the raw body and headers on your endpoint until you're happy with signature verification, then reduce logging in production.

7. Security checklist

• Always use HTTPS for your webhook endpoints.
• Store the signing secret in a secret manager or env var; never in source control.
• Verify x-matchaudit-signature on every request.
• Enforce an allowlist of IPs or reverse proxy rules if your infrastructure supports it.
• Return 2xx only after you have safely persisted the event and can retry work internally if needed.