Webhooks

SSH key verification sessions support these webhook events:

Event	When it fires
`new_connection`	A user connects to the verification session.
`verified`	SSHVerify matches a configured key.
`failed_attempt`	A connection attempt does not verify the session.
`status_changed`	The session status changes, for example from `pending` to `verified` or `failed`.

If a webhook has an empty events list, all verification events trigger it.

Common payload fields

Every verification event payload contains:

Field	Description
`verify_session_id`	ID of the verification session.
`verify_session_external_id`	Optional external ID configured on the session.
`verify_session_connection_identifier`	SSH username used to connect to the session.

These fields are nested inside the shared webhook envelope described in Webhooks.

`new_connection`

The new_connection payload includes connection metadata:

{
  "verify_session_id": "session_id",
  "verify_session_external_id": "user_123",
  "verify_session_connection_identifier": "connection_identifier",
  "verify_session_connection_id": "connection_id",
  "ip_address": "203.0.113.10",
  "client_version": "SSH-2.0-OpenSSH_9.6"
}

`verified`

The verified payload includes the matched key and connection-key record:

{
  "verify_session_id": "session_id",
  "verify_session_external_id": "user_123",
  "verify_session_connection_identifier": "connection_identifier",
  "verify_session_connection_id": "connection_id",
  "verify_session_key_id": "key_id",
  "verify_session_connection_key_id": "connection_key_id",
  "public_key_ssh": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...",
  "public_key_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "public_key_md5": "MD5:...",
  "public_key_sha256": "SHA256:...",
  "public_key_algorithm": "ssh-ed25519"
}

`status_changed`

The status_changed payload includes the new session status:

{
  "verify_session_id": "session_id",
  "verify_session_external_id": "user_123",
  "verify_session_connection_identifier": "connection_identifier",
  "verify_session_status": "verified"
}

`failed_attempt`

Use failed_attempt to react when a user connects without satisfying the verification rules. This is useful for notifying your application that a user may need to retry, use a different key, or contact support.