Webhook Endpoints

All examples on this page assume you've initialized the Node.js SDK. See Installation for setup.

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.

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

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"]
  }'

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

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.