Skip to main content
When a Kayle check reaches a terminal state, Kayle emits a domain event and delivers it to every webhook endpoint subscribed to that event type. Webhooks are the primary way you learn about Kayle check results — polling the API works for one-off lookups, but a subscribed endpoint is what you should build against.

​
Event types

Four event types exist:
EventTrigger
verification.session.succeededAn attempt was confirmed by Kayle. The payload includes the consented claims and the list of selected field keys.
verification.session.failedKayle could not confirm an attempt. The payload includes a failure_code.
verification.session.expiredA session passed its 60-minute window with no confirmed attempt.
verification.session.cancelledA session was cancelled by you (authenticated cancel), by the user (public cancel), or as a privacy-withdrawal replacement for a succeeded / failed payload that was scrubbed before delivery. The payload includes a reason and the per-check retry counters.
Each endpoint subscribes to a subset by listing event types when you create or update it. See Configuring endpoints. Every verification session produces exactly one terminal webhook from the set above — provided at least one of your endpoints subscribes to that event type. If a user withdraws consent (privacy request) after a succeeded or failed event was queued but before it delivered, the payload is scrubbed and a verification.session.cancelled event is emitted in its place. See verification.session.cancelled for the full reason enumeration.

​
Delivery semantics

  • At-least-once. Kayle retries failed deliveries. Build idempotent handlers — key on metadata.event_id (one ID per event, never reused) or on metadata.verification_session_id combined with the event type.
  • Per-endpoint. A single event triggers one delivery per subscribed endpoint. Disabling or deleting an endpoint does not affect other endpoints.
  • Best-effort ordering. Within a session you’ll usually receive events in the order they happened, but a delivery that retries can land after later events. Don’t rely on order; rely on metadata and the resource state you can fetch from the API.
  • Sub-minute latency for the first attempt. The first delivery is queued immediately when the event fires and processed by a scheduled job. See Deliveries for the retry schedule.

​
What you have to handle

Every endpoint must:
  1. Register an encryption key before it can receive deliveries. Webhook payloads are always JWE-encrypted; an endpoint without an active key fails delivery before the body is sent.
  2. Verify the X-Kayle-Signature header against the encrypted body before decrypting. See Verifying signatures.
  3. Respond with a 2xx status code within a few seconds. Anything else is treated as a delivery failure and retried.
  4. Be idempotent on metadata.event_id (or on metadata.verification_session_id + event type).
Endpoints that don’t return 2xx after the automatic retry schedule are marked failed. You can replay or retry them from the dashboard or via the API while the encrypted payload is still retained; see Deliveries.