Events

Every time something significant happens — a session is verified, a review is resolved, a trust-reuse grant changes — Stile creates an event. Webhooks and the Events API share the core id, object, type, data, and created envelope. The API enriches that envelope with version and delivery state for reconciliation; those API-only fields are not included in webhook POST bodies. Treat webhook delivery as the source of truth — poll this API on cold start or for reconciliation.

Examples show cURL, Python, Go, and Node.js. Approved preview users can also use the private-preview Node.js SDK as a typed convenience wrapper for the full event catalog.

The event object

{
  "id": "evt_abc123",
  "object": "event",
  "type": "verification_session.verified",
  "api_version": "2025-01-01",
  "livemode": true,
  "created": 1741564800,
  "pending_webhooks": 1,
  "data": {
    "object": {
      "id": "vks_xyz789",
      "object": "verification_session",
      "status": "verified",
      "type": "identity",
      "client_reference_id": "order_123",
      "current_method": "document_capture",
      "age_tier": "min_age_21",
      "jurisdiction": "US-CA",
      "jurisdiction_audit_declared": "US-CA",
      "jurisdiction_audit_ip_derived": "US-CA",
      "jurisdiction_audit_resolved": "US-CA",
      "jurisdiction_audit_source": "input_field",
      "jurisdiction_audit_mismatch": false,
      "verification_path": null,
      "workflow_version_id": "wfv_abc123",
      "livemode": true,
      "completed_at": 1741564800,
      "created": 1741561200,
      "verification_result": {
        "method": "document_capture",
        "confidence": 0.98,
        "age_verified": true,
        "age_estimate": 29,
        "identity_verified": true,
        "face_match_passed": true,
        "barcode_cross_ref_match": true,
        "liveness_score": 0.97
      }
    }
  },
  "delivery_summary": {
    "total": 1,
    "delivered": 1,
    "failed": 0,
    "pending": 0
  }
}

Retrieve an event

curl https://api.stile.id/v1/events/evt_abc123 \
  -H "Authorization: Bearer stile_sk_..."

import requests

res = requests.get(
    "https://api.stile.id/v1/events/evt_abc123",
    headers={"Authorization": "Bearer stile_sk_..."},
)
event = res.json()
print(event["type"])  # "verification_session.verified"

req, _ := http.NewRequest("GET", "https://api.stile.id/v1/events/evt_abc123", nil)
req.Header.Set("Authorization", "Bearer stile_sk_...")
res, _ := http.DefaultClient.Do(req)

const event = await stile.events.retrieve("evt_abc123");
console.log(event.type);  // "verification_session.verified"
console.log(event.data.object); // The verification-session event snapshot

List events

Returns a paginated list of events. Filter by type, time window, or session to reconcile your records against what Stile recorded.

Use only one cursor per request: starting_after moves toward older events and ending_before moves toward newer events.

curl "https://api.stile.id/v1/events?limit=50" \
  -H "Authorization: Bearer stile_sk_..."

import requests

res = requests.get(
    "https://api.stile.id/v1/events",
    headers={"Authorization": "Bearer stile_sk_..."},
    params={"limit": 50},
)
data = res.json()

req, _ := http.NewRequest("GET", "https://api.stile.id/v1/events?limit=50", nil)
req.Header.Set("Authorization", "Bearer stile_sk_...")
res, _ := http.DefaultClient.Do(req)

const { data } = await stile.events.list({ limit: 50 });

for (const event of data) {
  console.log(event.type, event.created);
}

Event types

The complete catalog. Events cover three areas: the verification session lifecycle (verification_session.*), manual review outcomes (session_review.*), and trust-reuse grants (trust_reuse_grant.*, trust_reuse_consent.*). Subscribe per endpoint via enabled_events — or use ["*"] to receive everything (see Webhook Endpoints).

Delivery status

pending_webhooks records how many endpoint deliveries were queued when the event was dispatched. It is retained for compatibility and does not decrement as deliveries finish.

Use delivery_summary.pending for the current number of unresolved deliveries. delivery_summary is computed from delivery records whenever you list or retrieve events. Inspect each endpoint's current delivery state with the deliveries API.

Deduplication

One event can produce multiple webhook delivery records — exactly one per subscribed endpoint. Retries update the original record rather than creating attempt-history rows. The event id is the stable identity across every endpoint delivery.

Next steps