Webhooks - AuthForge

Webhooks send HTTP POST requests to your server when events happen on your licenses; creation, validation, revocation, and more. Use them to sync license state with your backend, trigger workflows, or update your database.

How it works

You register a webhook URL in the dashboard or via the API.
When a matching event occurs, AuthForge sends an HTTP POST to your URL with a JSON payload.
Each request is signed with HMAC-SHA256 so you can verify it came from AuthForge.

Events

Event	Trigger
`license.validated`	Successful authentication via SDK
`license.created`	License key generated (dashboard or API)
`license.revoked`	License revoked
`license.activated`	Revoked license re-activated
`license.hwid_bound`	A new HWID was bound to a license slot by a successful validate
`license.hwid_reset`	HWID bindings cleared
`license.deleted`	License permanently deleted
`license.expired`	Once per expiry window, when validate or heartbeat sees `expiresAt` in the past (`data`: `licenseKey`, `expiresAt`)
`license.offline_file_minted`	Fresh offline-file mint only (`data`: `licenseKey`, `jti`, `expiresAt`, `hwidPolicy`, `kid`, `fileSha256`, `source`)

license.validated fires on every successful SDK login. For high-traffic apps, consider subscribing only to the events you need.

Payload format

Every webhook delivery sends a JSON body like this:

{
  "id": "evt_3f2a9c1b8e7046d0a1b2c3d4e5f60718",
  "event": "license.validated",
  "timestamp": "2026-04-10T15:30:00.000Z",
  "data": {
    "licenseKey": "A3K9-BFWX-7NP2-QHDT",
    "appId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "active",
    "hwid": "a1b2c3d4e5f6..."
  }
}

Headers

Header	Description
`Content-Type`	`application/json`
`X-AuthForge-Event`	The event name (e.g., `license.validated`)
`X-AuthForge-Event-Id`	Stable event id (`evt_` + hex). Same value as the body’s `id`. Deduplicate on this.
`X-AuthForge-Timestamp`	ISO 8601 timestamp of the event (not covered by any signature; use `t` from `X-AuthForge-Signature-V2` for freshness checks)
`X-AuthForge-Signature-V2`	Recommended. `t=<unix seconds>,v1=<hex>` where `<hex>` is HMAC-SHA256 of `<t>.<raw request body>`
`X-AuthForge-Signature`	Legacy. `sha256=<hex>` where `<hex>` is HMAC-SHA256 of the raw request body only

Signature verification

Every webhook is signed using the secret generated when you created the webhook. Always verify the signature before processing. Verify X-AuthForge-Signature-V2. It signs the send time together with the body, so an attacker who captures a delivery can’t replay it later or change its timestamp:

X-AuthForge-Signature-V2: t=1726963200,v1=<hex>

<hex> = HMAC-SHA256(webhook_secret, "<t>.<raw_request_body>")

To verify:

Split the header on , and read the t and v1 values.
Reject the request if t is more than 5 minutes away from your current time.
Compute HMAC-SHA256 of the string <t>. followed by the raw request body (the exact bytes you received, before JSON parsing), keyed by your webhook secret.
Compare your hex digest with v1 using a constant-time comparison.

Retries resend the same body with a fresh t, so the V2 header differs between attempts. Deduplicate on the body’s id (also sent as X-AuthForge-Event-Id). Retries reuse that id and only change t.

Verification example (Node.js / Express)

const crypto = require("crypto");

const TOLERANCE_SECONDS = 5 * 60;

function verifyAuthForgeSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(
    (header || "").split(",").map((part) => part.trim().split("=", 2))
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.`)
    .update(rawBody)
    .digest("hex");
  const sigBuf = Buffer.from(parts.v1, "hex");
  const expectedBuf = Buffer.from(expected, "hex");
  return sigBuf.length === expectedBuf.length && crypto.timingSafeEqual(sigBuf, expectedBuf);
}

app.post("/webhooks/authforge", express.raw({ type: "application/json" }), (req, res) => {
  const valid = verifyAuthForgeSignature(
    req.body,
    req.headers["x-authforge-signature-v2"],
    process.env.AUTHFORGE_WEBHOOK_SECRET
  );
  if (!valid) {
    return res.status(401).send("Invalid or stale signature");
  }

  const event = JSON.parse(req.body);
  console.log(`Received ${event.event} for ${event.data.licenseKey}`);

  // Handle the event
  switch (event.event) {
    case "license.validated":
      // Update last-seen timestamp in your DB
      break;
    case "license.revoked":
      // Suspend user access in your system
      break;
    case "license.created":
      // Send welcome email
      break;
  }

  res.sendStatus(200);
});

Verification example (Python / Flask)

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

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["AUTHFORGE_WEBHOOK_SECRET"]
TOLERANCE_SECONDS = 5 * 60

def verify_authforge_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
    try:
        t = int(parts["t"])
        signature = parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{t}.".encode() + raw_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.route("/webhooks/authforge", methods=["POST"])
def handle_webhook():
    header = request.headers.get("X-AuthForge-Signature-V2", "")
    if not verify_authforge_signature(request.get_data(), header, WEBHOOK_SECRET):
        abort(401)

    event = request.get_json()
    print(f"Received {event['event']} for {event['data']['licenseKey']}")

    # Handle the event...

    return "", 200

Legacy signature (`X-AuthForge-Signature`)

X-AuthForge-Signature is still sent on every delivery so existing integrations keep working. It is sha256= followed by HMAC-SHA256 of the raw body alone, which means it doesn’t cover X-AuthForge-Timestamp: a captured request can be replayed, or its timestamp changed, without breaking the signature. Switch to X-AuthForge-Signature-V2 when you can.

Setup

Via the dashboard

Go to your app’s Settings → Webhooks
Click Add Webhook
Enter your HTTPS endpoint URL
Select which events to subscribe to (or select all)
Click Create
Copy the webhook secret: it’s shown only once

Via the Developer API

curl -X POST https://api.authforge.cc/v1/apps/YOUR_APP_ID/webhooks \
  -H "Authorization: Bearer af_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/authforge",
    "events": ["license.created", "license.revoked"],
    "enabled": true
  }'

The response includes a secret field; store it securely for signature verification.

Limits

Limit	Value
Max webhooks per app	5
Delivery timeout	10 seconds
Retries	Up to 3 after a network error, timeout, or 5xx response, waiting about 1s, 5s, then 25s between attempts
Redirects	Not followed. A 3xx response counts as a failed delivery and is not retried

Testing

Use the test endpoint to send a sample payload to your webhook URL:

curl -X POST https://api.authforge.cc/v1/apps/YOUR_APP_ID/webhooks/WEBHOOK_ID/test \
  -H "Authorization: Bearer af_live_your_key"

This sends a signed test.ping event to verify your endpoint is receiving and verifying payloads correctly.

Next steps

Webhooks API Reference; Full endpoint documentation
Commerce; Stripe checkout into licenses; subscribe to license.created for your own fulfilment

​How it works

​Events

​Payload format

​Headers

​Signature verification

​Verification example (Node.js / Express)

​Verification example (Python / Flask)

​Legacy signature (X-AuthForge-Signature)

​Setup

​Via the dashboard

​Via the Developer API

​Limits

​Testing

​Next steps

How it works

Events

Payload format

Headers

Signature verification

Verification example (Node.js / Express)

Verification example (Python / Flask)

Legacy signature (`X-AuthForge-Signature`)

Setup

Via the dashboard

Via the Developer API

Limits

Testing

Next steps