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. (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. VerifyX-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:
- Split the header on
,and read thetandv1values. - Reject the request if
tis 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
v1using 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.
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
- 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
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 withenabled: 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: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
- Webhooks API Reference; Full endpoint documentation
- Commerce; Stripe checkout into licenses; subscribe to
license.createdfor your own fulfilment