Webhook

Webhooks notify your application when something changes in an SSH key collection or verification session. You can create webhooks from the web app or API, either when creating a session or later from the session details.

Feature-specific events and payload examples are documented in SSH Key Collection webhooks and SSH Key Verification webhooks.

Configuration

Each webhook has these settings:

Field	Description
url	HTTP or HTTPS URL to call.
method	HTTP method: post, put, or patch. Defaults to post.
headers	Optional headers to send with each request.
events	Optional event allowlist. When empty, all events for the session trigger the webhook.
retries	Maximum number of retry attempts after a failed delivery. Defaults to 0.
initial_backoff	Delay before the first retry, in seconds. Defaults to 10.
backoff_multiplier	Multiplier applied to each later retry delay. Defaults to 2.

Payload envelope

Every webhook request sends a JSON payload with the same top-level shape:

{
  "entity": "collect_session",
  "id": "session_id",
  "event": "status_changed",
  "webhook_id": "webhook_id",
  "webhook_invocation_id": "invocation_id",
  "trigger_time": "2026-05-10T10:00:00Z",
  "request_time": "2026-05-10T10:00:01Z",
  "attempt": 1,
  "payload": {}
}

The nested payload object depends on the feature and event.

Webhook order

When no delivery errors occur, webhooks are queued in event order. Failed deliveries are retried later, so another event can be delivered first. Design your receiver to be idempotent and use webhook_invocation_id, event, and the session ID to deduplicate and reconcile state.

Retries

SSHVerify treats DNS failures, certificate failures, timeouts, unknown delivery errors, and non-success HTTP responses as failed deliveries. Failed invocations are visible from the web app, including the response status, response body, and failure reason when available.

Retry delay is calculated from initial_backoff * backoff_multiplier^(attempt - 1). For example, the default retry settings wait 10 seconds before the first retry, 20 seconds before the next retry, then 40 seconds, and so on.