Webhooks API Reference

Manage webhook endpoints that receive real-time notifications when license events occur.

Create a webhook

Path parameters

Param	Type	Description
`appId`	string	The application ID

Request body

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint URL to receive events
`events`	string[]	Yes	Array of event names to subscribe to
`enabled`	boolean	No	Whether the webhook is active (default `true`)

Available events

license.validated, license.created, license.revoked, license.activated, license.hwid_bound, license.hwid_reset, license.deleted, license.expired, license.offline_file_minted

Example

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
  }'

Response (201)

{
  "webhookId": "wh_a1b2c3d4e5f6",
  "appId": "YOUR_APP_ID",
  "url": "https://your-server.com/webhooks/authforge",
  "events": ["license.created", "license.revoked"],
  "enabled": true,
  "secret": "whsec_7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c",
  "createdAt": "2026-04-10T12:00:00.000Z"
}

The secret field is returned only on creation. Store it securely; you’ll need it to verify webhook signatures. It cannot be retrieved again.

Errors

HTTP	Code	Cause
400	`bad_request`	Invalid URL, empty events array, or invalid event name
403	`forbidden`	The app doesn’t belong to your account
409	`webhook_limit_reached`	Max 5 webhooks per app exceeded

List webhooks

List all webhooks for an application.

Example

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

Response (200)

{
  "webhooks": [
    {
      "webhookId": "wh_a1b2c3d4e5f6",
      "appId": "YOUR_APP_ID",
      "url": "https://your-server.com/webhooks/authforge",
      "events": ["license.created", "license.revoked"],
      "enabled": true,
      "lastDeliveryAt": "2026-04-10T15:30:00.000Z",
      "lastDeliveryStatus": 200,
      "createdAt": "2026-04-10T12:00:00.000Z"
    }
  ]
}

The secret field is not returned in list responses for security.

Update a webhook

Update the URL, events, or enabled status of an existing webhook.

Path parameters

Param	Type	Description
`appId`	string	The application ID
`webhookId`	string	The webhook ID

Request body

All fields are optional; only included fields are updated.

Field	Type	Description
`url`	string	New endpoint URL
`events`	string[]	New event subscriptions
`enabled`	boolean	Enable or disable the webhook

Example

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

Response (200)

{ "ok": true }

Delete a webhook

Permanently delete a webhook endpoint.

Example

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

Response (200)

{ "ok": true }

Test a webhook

Send a test event to the webhook endpoint. Returns the HTTP status code from your server. Requires the write:webhooks scope.

Example

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

Response (200)

{
  "ok": true,
  "status": 200
}

ok is true only for a 2xx response. Redirects are not followed, so a 3xx comes back as ok: false with that status. If AuthForge can’t reach your endpoint (a network error, a timeout, or a blocked host), the response is:

{
  "ok": false,
  "status": 0,
  "error": "Delivery failed"
}

The test sends one test.ping event, whose data is { "webhookId": ..., "appId": ... }, signed with the webhook’s secret and carrying the same headers as a real delivery. It is not retried. A key with only read:webhooks gets a 403 insufficient_scope, and a webhook ID from another app returns 404 not_found.

Webhook payload format

Every webhook delivery sends an HTTP POST with these headers and body:

Headers

Header	Value
`Content-Type`	`application/json`
`X-AuthForge-Event`	Event name (e.g., `license.revoked`)
`X-AuthForge-Event-Id`	Stable event id (`evt_` + hex). Same value as the body’s `id`.
`X-AuthForge-Timestamp`	ISO 8601 timestamp (unsigned)
`X-AuthForge-Signature-V2`	Recommended. `t=<unix seconds>,v1=<hex>` where `<hex>` is `HMAC-SHA256(secret, "<t>.<body>")`
`X-AuthForge-Signature`	Legacy. `sha256=<hex>` where `<hex>` is `HMAC-SHA256(secret, body)`

Body

{
  "id": "evt_3f2a9c1b8e7046d0a1b2c3d4e5f60718",
  "event": "license.revoked",
  "timestamp": "2026-04-10T15:30:00.000Z",
  "data": {
    "licenseKey": "A3K9-BFWX-7NP2-QHDT",
    "appId": "YOUR_APP_ID",
    "status": "revoked"
  }
}

The data object varies by event type but always includes licenseKey and appId. id is generated once per event and sent again on every retry. Deduplicate on id (or the X-AuthForge-Event-Id header). Retries reuse that id and only change the signature timestamp t.

Signature verification

Verify X-AuthForge-Signature-V2 and reject deliveries whose t is more than 5 minutes from your clock:

const crypto = require("crypto");

const parts = Object.fromEntries(
  (req.headers["x-authforge-signature-v2"] || "")
    .split(",")
    .map((part) => part.trim().split("=", 2))
);
const t = Number(parts.t);
const fresh =
  Number.isInteger(t) && Math.abs(Math.floor(Date.now() / 1000) - t) <= 5 * 60;

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

const sigBuf = Buffer.from(parts.v1 || "", "hex");
const expectedBuf = Buffer.from(expected, "hex");
const valid =
  fresh &&
  sigBuf.length === expectedBuf.length &&
  crypto.timingSafeEqual(sigBuf, expectedBuf);

The legacy X-AuthForge-Signature header covers only the body and is kept for existing integrations. See Webhooks for full verification examples in Node.js and Python.

​Create a webhook

​Path parameters

​Request body

​Available events

​Example

​Response (201)

​Errors

​List webhooks

​Example

​Response (200)

​Update a webhook

​Path parameters

​Request body

​Example

​Response (200)

​Delete a webhook

​Example

​Response (200)

​Test a webhook

​Example

​Response (200)

​Webhook payload format

​Headers

​Body

​Signature verification

Create a webhook

Path parameters

Request body

Available events

Example

Response (201)

Errors

List webhooks

Example

Response (200)

Update a webhook

Path parameters

Request body

Example

Response (200)

Delete a webhook

Example

Response (200)

Test a webhook

Example

Response (200)

Webhook payload format

Headers

Body

Signature verification