Events

Every time something significant happens — a session is verified, a review is resolved, a trust-reuse grant changes — Stile creates an event. Webhook deliveries POST these same event objects to your endpoints; the Events API lets you retrieve and list them on demand. 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. You can also use the Node.js SDK as a typed convenience wrapper.

The event object

{
  "id": "evt_abc123",
  "object": "event",
  "type": "verification_session.verified",
  "created": 1741564800,
  "pending_webhooks": 0,
  "data": {
    "id": "vks_xyz789",
    "object": "verification_session",
    "status": "verified",
    "type": "identity",
    "client_reference_id": "user_123",
    "expires_at": 1741651200,
    "completed_at": 1741564800,
    "created": 1741561200
  }
}

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);  // The verification session object

List events

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

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).

Pending webhooks

The pending_webhooks field indicates how many webhook deliveries are still queued for this event. Once all subscribed endpoints have acknowledged the delivery (HTTP 2xx), it drops to 0. Endpoints with delivery failures continue retrying on the automatic schedule — see retry behavior in the Webhooks guide.

A non-zero pending_webhooks on an older event is a useful health signal: it means at least one of your endpoints hasn't accepted the delivery yet. Inspect the failing deliveries via the deliveries API.

Deduplication

One event can produce multiple webhook deliveries — one per subscribed endpoint, plus retries after failures. The event id is the stable identity across all of them.

Next steps