Skip to main content
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

  1. You register a webhook URL in the dashboard or via the API.
  2. When a matching event occurs, AuthForge sends an HTTP POST to your URL with a JSON payload.
  3. Each request is signed with HMAC-SHA256 so you can verify it came from AuthForge. (Discord webhooks are the exception; see Discord.)

Events

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:

Headers

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:
To verify:
  1. Split the header on , and read the t and v1 values.
  2. Reject the request if t is more than 5 minutes away from your current time.
  3. 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.
  4. 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)

Verification example (Python / Flask)

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.

Discord

Paste a Discord channel webhook URL (https://discord.com/api/webhooks/...) and AuthForge posts each event to the channel as a message, with no server needed. Each event becomes one embed. The dashboard and the API pick the discord format for you when the URL is a Discord webhook. A webhook has a format: Any other pairing is rejected with 400 invalid_webhook_format. Changing a webhook’s URL without a format picks the format from the new URL. Webhooks created before formats existed keep working: a Discord URL among them is delivered as discord. Discord messages show only the last four characters of a license key and a short hashed device tag. They never include an IP address or email, because a channel is often visible to more people than your dashboard, and they disable mentions.
Discord messages are not signed, because Discord does not check signatures, and no signing secret is shown for a Discord webhook. The webhook URL is the credential, so keep it private.
license.validated fires on every login and is usually too noisy for a channel. Discord also rate-limits bursts, such as a 100-license bulk create. AuthForge retries those, see Limits.

Setup

Via the dashboard

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

Via the Developer API

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

Limits

Automatic disabling

If 10 events in a row cannot be delivered to an endpoint, including every retry, AuthForge switches the webhook off and emails the account owner. The dashboard shows it as Auto-disabled, and the API returns it with enabled: false and disabledReason: "consecutive_failures". A successful delivery (any 2xx) resets the count, so an endpoint that only fails now and then is never switched off. A 429 never counts toward the ten: the endpoint is up and only asked for a slower pace. To turn it back on, fix the endpoint, use the test endpoint to confirm it returns a 2xx, then set enabled: true in the dashboard or with PUT /v1/apps/:appId/webhooks/:webhookId. Re-enabling does not reset the failure count: if the next event also fails, the webhook is switched off again straight away. Events that fired while it was off are not replayed.

Testing

Use the test endpoint to send a sample payload to your webhook URL:
This sends a signed test.ping event to verify your endpoint is receiving and verifying payloads correctly. For a discord webhook the ping is posted as a Discord message and is not signed.

Next steps