Webhook Endpoints

A webhook endpoint is an HTTPS URL on your server where Stile delivers signed events — session verified, failed, expired, and more. This page covers the management API: creating endpoints, rotating secrets, and inspecting individual deliveries. For signature verification and handler patterns, see the Webhooks guide. You can also manage endpoints in the dashboard.

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.

The webhook endpoint object

Create an endpoint

Your endpoint should be a publicly reachable HTTPS URL and must respond with a 2xx within 30 seconds. Use an HTTPS tunnel for a local handler. Return a 2xx as soon as you've queued the work, then process asynchronously.

curl https://api.stile.id/v1/webhook_endpoints \
  -H "Authorization: Bearer stile_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/api/webhooks",
    "enabled_events": ["verification_session.verified", "verification_session.failed"]
  }'

import requests

res = requests.post(
    "https://api.stile.id/v1/webhook_endpoints",
    headers={"Authorization": "Bearer stile_sk_..."},
    json={
        "name": "Production verification",
        "url": "https://yourapp.com/api/webhooks",
        "enabled_events": [
            "verification_session.verified",
            "verification_session.failed",
        ],
        "description": "Production webhook",
    },
)
endpoint = res.json()

# IMPORTANT: save endpoint["secret"] — it's only shown once!
print("Webhook secret:", endpoint["secret"])

body := strings.NewReader(`{
  "name": "Production verification",
  "url": "https://yourapp.com/api/webhooks",
  "enabled_events": ["verification_session.verified", "verification_session.failed"],
  "description": "Production webhook"
}`)
req, _ := http.NewRequest("POST", "https://api.stile.id/v1/webhook_endpoints", body)
req.Header.Set("Authorization", "Bearer stile_sk_...")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

const endpoint = await stile.webhookEndpoints.create({
  name: "Production verification",
  url: "https://yourapp.com/api/webhooks",
  enabled_events: [
    "verification_session.verified",
    "verification_session.failed",
    "verification_session.expired",
  ],
  description: "Production webhook",
});

// IMPORTANT: save endpoint.secret — it's only shown once!
console.log("Webhook secret:", endpoint.secret);

Retrieve an endpoint

curl https://api.stile.id/v1/webhook_endpoints/we_abc123 \
  --header "Authorization: Bearer $STILE_API_KEY"

The secret is not included — it is only returned on create and rotate.

Update an endpoint

curl https://api.stile.id/v1/webhook_endpoints/we_abc123 \
  --request POST \
  --header "Authorization: Bearer $STILE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "enabled_events": ["*"], "status": "disabled" }'

Delete an endpoint

curl https://api.stile.id/v1/webhook_endpoints/we_abc123 \
  --request DELETE \
  --header "Authorization: Bearer $STILE_API_KEY"

List endpoints

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

import requests

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

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

const { data } = await stile.webhookEndpoints.list();

Rotate the signing secret

Generates a new signing secret for the endpoint and returns it once.

curl -X POST https://api.stile.id/v1/webhook_endpoints/we_abc123/rotate-secret \
  -H "Authorization: Bearer stile_sk_..."

List deliveries

Returns a paginated list of delivery records for a specific endpoint, newest first. Stile creates one record for each event-endpoint pair and updates that record on every retry. Each record contains the current attempt number and latest HTTP response; it is not an immutable attempt history. The record ID is also sent as the Stile-Webhook-Id header.

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

curl "https://api.stile.id/v1/webhook_endpoints/we_abc123/deliveries?limit=10" \
  --header "Authorization: Bearer $STILE_API_KEY"

Retrieve a delivery

Returns the current detail for one delivery record, including its request payload, current attempt number, and latest response from your endpoint. Earlier retry responses are not retained on this resource.

curl https://api.stile.id/v1/webhook_endpoints/we_abc123/deliveries/cm5x7k9h20000qwerty123456 \
  --header "Authorization: Bearer $STILE_API_KEY"

Retry a delivery

Re-queues an existing delivery immediately. The same delivery record and Stile-Webhook-Id are reused, and its attempt counter and latest response fields are reset before processing resumes. Use this after fixing an endpoint instead of waiting for the automatic retry schedule (5 min → 30 min → 2 h → 8 h after the initial failure; see the Webhooks guide).

curl -X POST https://api.stile.id/v1/webhook_endpoints/we_abc123/deliveries/cm5x7k9h20000qwerty123456/retry \
  -H "Authorization: Bearer stile_sk_..."

Send a test event

Queue a synthetic event to confirm that the endpoint is reachable and your handler accepts the payload. Omit event_type to send verification_session.verified.

curl https://api.stile.id/v1/webhook_endpoints/we_abc123/test \
  --request POST \
  --header "Authorization: Bearer $STILE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "event_type": "verification_session.verified" }'

The response contains both the queued event id and its endpoint-specific delivery_id. Retrieve that delivery until it reaches delivered or failed; accepting the test request does not itself prove that your endpoint returned 2xx.

{
  "id": "evt_test_123",
  "object": "event",
  "type": "verification_session.verified",
  "created": 1786400000,
  "delivery_id": "whd_test_123"
}

Automatic and manual retries reuse the original event id and delivery ID. Another subscribed endpoint has its own delivery record for the same event, so deduplicate business work on the event id.

Event types

See the full catalog in the Events API reference — verification session lifecycle (verification_session.*), manual review outcomes (session_review.*), and trust-reuse grants (trust_reuse_grant.*, trust_reuse_consent.*). Use ["*"] in enabled_events to subscribe to everything.

Next steps