Webhooks overview

Webhooks notify your servers about important events in k-ID, such as challenge status changes and verification results. Configure webhook URLs and secrets in Compliance Studio under Developer Settings for each Product.

Payloads include an eventType and a data object. See Event types for payload schemas.

Event types

Event Type	Description
Challenge.StateChange	Emitted when a parental consent challenge changes state
Verification.Result	Emitted with the result of a verification attempt
Verification.Revoke	Emitted when a previously passed verification has been revoked
Account.Delete	Emitted when an account is deleted
AgeAssurance.Result	Emitted with the result of an Age Assurance evaluation (deprecated, replaced by Verification.Result)
Session.ChangePermissions	Emitted when session permissions are modified by a parent
Session.Delete	Emitted when a session is deleted
Test	Used to verify that the webhook is working correctly

Signature validation

Validate webhook requests with the configured webhook secret.

Headers

Headers sent with each request:

• X-Signature-Timestamp: UNIX epoch seconds
• X-Signature-Hmac-Sha256: HMAC SHA-256 of (timestamp + raw body), using the webhook secret as key, hex-encoded (lowercase)

Expected behavior

• Return 200 for valid signatures
• Return 401 for invalid signatures

For implementation details, see Validating Webhook Requests.

Delivery, retries, and recovery

Delivery guarantees

k-ID delivers webhook events with an at-least-once guarantee. Your endpoint can receive the same event more than once, so design your handler to be idempotent. Use the data.id field (the verification or challenge ID) to deduplicate events you have already processed.

Retry policy

When your endpoint returns a non-200 status code or the request times out, k-ID retries delivery 2 times:

Attempt	Delay after previous attempt
First retry	5 seconds
Second retry	10 seconds

After the initial attempt plus two retries (three total attempts), k-ID stops trying to deliver that event.

Handling missed webhooks

If your server was down or a webhook wasn't delivered successfully, recover by polling the relevant status endpoint from your server by using the ID you saved when you started the flow:

• Verifications: GET /age-verification/get-status with the verification ID
• Challenges: GET /challenge/get-status with the challenge ID

Recommended pattern

Always save the verification or challenge ID that you receive when you initiate a flow. If your webhook handler doesn't receive a result within the expected time frame, call the corresponding get-status endpoint to retrieve the current state. This redirect-then-poll pattern ensures you never miss a result, even if all webhook deliveries fail.

Handling duplicate events

Webhook events are idempotent. The same event can be delivered more than once, for example when a network issue causes an ambiguous delivery status. Always check whether you have already processed an event before acting on it. A simple approach is to track processed event IDs (the data.id field) and skip duplicates.