Webhooks

Webhooks let you subscribe to events happening in the k-ID Engine as they happen, as opposed to polling an API to see if data is available.

Webhooks can be used for a variety of purposes, such as:

1. Handling adult verification results
2. Handling age assurance results
3. Handling challenge state changes

Setting Up Webhooks

Webhooks are configured in the Publisher Portal, by specifying a URL that the k-ID Engine will call when an event occurs. The URL must be a secure HTTPS URL. The k-ID Engine will send a POST request to the URL with a JSON payload that contains the event data.

Webhook Event Structure

The JSON payload sent to the webhook URL will contain the following fields:

• eventType - The type of event that occurred.
• data - The data associated with the event.

An X-Event-Type header will also be sent with the event type.

In the future, additional headers will be sent in order to verify the authenticity of the request.

Webhook Event Types

The following event types are available:

• AdultVerification.Result
• AgeAssurance.Result
• Challenge.StateChange
• Session.ChangePermissions
• Session.Delete

Adult Verification Result

Properties:

• id - The unique verification ID.
• status - Can be PASS, FAIL, or INCONCLUSIVE.
• ageRange (optional) - Details about the estimated age range.

ageRange properties:

• minAge - The estimated minimum age.
• maxAge - The estimated maximum age.
• confidence - A number between 0 and 1 indicating the confidence in the estimated age range.

Example payload:

{
  "eventType": "AdultVerification.Result",
  "data": {
    "id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
    "status": "PASS"
  }
}

Age Assurance Result

Properties:

• id - The unique verification ID.
• status - Can be PASS, FAIL, or INCONCLUSIVE.
• ageRange (optional) - Details about the estimated age range.

ageRange properties:

• minAge - The estimated minimum age.
• maxAge - The estimated maximum age.
• confidence - A number between 0 and 1 indicating the confidence in the estimated age range.

Example payload:

{
  "eventType": "AgeAssurance.Result",
  "data": {
    "id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
    "status": "PASS",
    "ageRange": {
      "minAge": 18,
      "maxAge": 25,
      "confidence": 0.8
    }
  }
}

Challenge State Change

Properties:

• id - The challenge ID.
• productId - The product ID.
• status - Can be PASS, FAIL, or IN_PROGRESS.
• sessionId (optional) - If the status is PASS, the session ID.
• approverEmail (optional) - If the status is PASS, the email of the approver.

Example payload:

{
  "eventType": "Challenge.StateChange",
  "data": {
    "id": "683409f1-2930-4132-89ad-827462eed9af",
    "productId": 42,
    "status": "PASS",
    "sessionId": "0ad1641f-c154-4cc2-8bb2-74dbd0de7723",
    "approverEmail": "user@example.com"
  }
}

Session Change Permissions

Properties:

• id - The session ID.
• productId - The product ID.

Example payload:

{
  "eventType": "Session.ChangePermissions",
  "data": {
    "id": "78c299b2-5c33-4bde-84fe-8fc950fc7a96",
    "productId": 42,
  }
}

Session Delete

Properties:

• id - The session ID.
• productId - The product ID.

Example payload:

{
  "eventType": "Session.Delete",
  "data": {
    "id": "2d064cf7-0726-4193-b19a-8bd387937e60",
    "productId": 42,
  }
}