Webhook Endpoints

Examples show cURL, Python, Go, and Node.js. You can also use the Node.js SDK as a typed convenience wrapper.

Create an endpoint

POST/v1/webhook_endpoints

Parameter	Type	Description
`url`required	`string`	The HTTPS URL to deliver events to.
`enabled_events`required	`string[]`	Event types to subscribe to. Use ["*"] to receive all events.
`description`	`string`	A human-readable label for this endpoint.
`metadata`	`object`	Up to 50 key-value string pairs.

curl https://api.stile.dev/v1/webhook_endpoints \
  -H "Authorization: Bearer vk_test_..." \
  -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.dev/v1/webhook_endpoints",
    headers={"Authorization": "Bearer vk_test_..."},
    json={
        "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(`{
  "url": "https://yourapp.com/api/webhooks",
  "enabled_events": ["verification_session.verified", "verification_session.failed"],
  "description": "Production webhook"
}`)
req, _ := http.NewRequest("POST", "https://api.stile.dev/v1/webhook_endpoints", body)
req.Header.Set("Authorization", "Bearer vk_test_...")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

const endpoint = await stile.webhookEndpoints.create({
  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

GET/v1/webhook_endpoints/:id

const endpoint = await stile.webhookEndpoints.retrieve("we_abc123");

Update an endpoint

POST/v1/webhook_endpoints/:id

Parameter	Type	Description
`url`	`string`	New delivery URL.
`enabled_events`	`string[]`	Replace the subscribed event types.
`status`	`"enabled" \| "disabled"`	Pause or resume delivery without deleting the endpoint.
`description`	`string`	Update the label.
`metadata`	`object`	Replace all metadata key-value pairs.

// Subscribe to all events
await stile.webhookEndpoints.update("we_abc123", {
  enabled_events: ["*"],
});

// Temporarily pause delivery
await stile.webhookEndpoints.update("we_abc123", {
  status: "disabled",
});

Delete an endpoint

DELETE/v1/webhook_endpoints/:id

await stile.webhookEndpoints.del("we_abc123");

List endpoints

GET/v1/webhook_endpoints

curl https://api.stile.dev/v1/webhook_endpoints \
  -H "Authorization: Bearer vk_test_..."

import requests

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

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

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

List deliveries

GET/v1/webhook_endpoints/:id/deliveries

Returns a paginated list of delivery attempts for a specific endpoint, newest first. Useful for debugging failed deliveries and monitoring webhook health.

Parameter	Type	Description
`limit`	`number`= 20	Number of deliveries to return.
`starting_after`	`string`	Delivery ID cursor for pagination.

const { data } = await stile.webhookEndpoints.listDeliveries("we_abc123", {
  limit: 10,
});

for (const delivery of data) {
  console.log(delivery.event_type, delivery.response_status, delivery.attempt);
}

Event types

Event type	Trigger
`verification_session.created`	A new verification session was created.
`verification_session.processing`	A verification method started processing.
`verification_session.requires_input`	A method requires additional user input.
`verification_session.verified`	The session completed successfully.
`verification_session.failed`	All verification methods were exhausted.
`verification_session.cancelled`	The session was cancelled.
`verification_session.expired`	The session expired without completion.