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
Account.Delete	Emitted when an account is deleted
AgeAssurance.Result	Emitted with the result of an Age Assurance evaluation (deprecated, replaced by Verification.Result)
ParentalConsent.Granted	Emitted when parental consent is granted
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.