Create a webhook
Path parameters
Request body
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
Response (201)
Errors
List webhooks
Example
Response (200)
The
secret field is not returned in list responses for security.format is always present. Webhooks created before formats existed report discord for a Discord URL and raw otherwise, which is how they are delivered.
consecutiveFailures counts events in a row whose delivery failed after every retry; any 2xx resets it. A webhook that was switched off automatically also has disabledAt and disabledReason: "consecutive_failures". See Automatic disabling.
Update a webhook
Path parameters
Request body
All fields are optional; only included fields are updated.Example
Response (200)
Delete a webhook
Example
Response (200)
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
Response (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:
test.ping event, whose data is { "webhookId": ..., "appId": ... }, signed with the webhook’s secret and carrying the same headers as a real delivery. For a discord webhook the ping is posted as a Discord message instead and is not signed. 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. Each account can send 10 test pings per 10 minutes; past that the response is 429 rate_limited with Retry-After. Creates, edits and deletes share a separate allowance of 60 per hour per account, and update and delete return the same 429 once it is used up.
Webhook payload format
Every webhook delivery sends an HTTP POST with these headers and body:Headers
Body
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
VerifyX-AuthForge-Signature-V2 and reject deliveries whose t is more than 5 minutes from your clock:
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.