Webhook Events

Webhook Events allow for real-time logging of SSH sessions,

certificate creation, certificate expiration, and certificate revocation events. You can use Webhook Events to:

Alert on certificate expiry - Prevent certificate expiry related outages with proactive notifications on upcoming expirations.
Stream events to monitoring solutions - Push detailed certificate information to third-party monitoring and alerting systems.
Monitor certificate operations - Ensure your automated certificate toolchain is operating as expected.

Webhook event types

We currently have four webhook event types, namely:

SSH: Sends a webhook event for SSH start and stop sessions and user change events.
Expiration: Sends a webhook event for Certificate Manager when a certificate is within the last 25% of its lifetime, and again when it expires.
Certificate: Sends a webhook event for Certificate Manager with basic certificate details whenever a certificate is created, expires, or is revoked.
All: Sends events for everything above, for both SSH and Certificate Manager.

Note: We do not send certificate expiration events for OIDC certificates, to minimize noise, since they're usually short-lived. However, certificate creation events for such certificates will always be sent.

Using webhook events

To register a webhook, go to Settings > Webhooks and fill out the form as shown below:

Webhook events response formats

Here are examples of the response data you should expect to receive for each webhook event type:

SSH 'session start' event

{
  "category": "ssh-session",
  "hostname": "example-host.example.com",
  "username": "tester",
  "id": "d0547bbd-aab6-4531-b809-868f60d0bda7",
  "timestamp": "2022-08-01 20:29:23.333679027 +0000 UTC",
  "type": "start"
}

SSH 'session end' event

{
  "category": "ssh-session",
  "hostname": "example-host.example.com",
  "username": "tester",
  "id": "d0547bbd-aab6-4531-b809-868f60d0bda7",
  "timestamp": "2022-08-01 20:32:14.816883566 +0000 UTC",
  "type": "end"
}

SSH 'user change' event

{
  "category": "ssh-session",
  "hostname": "example-host.example.com",
  "username": "root",
  "id": "d0547bbd-aab6-4531-b809-868f60d0bda7",
  "timestamp": "2022-08-01 20:31:47.771260977 +0000 UTC",
  "type": "user_change"
}

Where:

Parameter	Description
category	The webhook event type. One of `ssh-session`, `certificate-request`, `certificate-expiration`, or `certificate-revocation`.
hostname	The name of the registered host
username	The posix username of the user responsible for the ssh session
id	The Smallstep ssh session id
timestamp	The time at which the event occurred
type	The specific type of SSH event type

Certificate creation event

{
  "category": "certificate-request",
  "authorityId": "5c780190-4e4e-4c5a-9331-50be29b28e21",
  "serialNumber": "217736770851791642908500119529647273613",
  "id": "4f2f0c29-704a-46f8-8f90-f7f74675b169",
  "notBefore": "2022-08-01T20:36:51.000Z",
  "notAfter": "2022-08-01T20:42:51.000Z",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIICITCCAcegAwIBAgIQOyXzxXEspOAfi/10+hPMLjAKBggqhkjOPQQDAjAhMR8w\nHQYDVQQDExZKV0sgU0EgSW50ZXJtZWRpYXRlIENBMB4XDTIyMDgwMTIwMzY1MVoX\nDTIyMDgwMTIwNDI1MVowFDESMBAGA1UEAxMJbXlzZXJ2aWNlMFkwEwYHKoZIzj0C\nAQYIKoZIzj0DAQcDQgAEfDkIN/DlpolcxVqMu5iZ0zJqVlAXfasCJvGxwBJKpQdS\nZJOLsenrguwJJpLqNuj3icIhI6gFodqvLpNAcaJ/zKOB7TCB6jAOBgNVHQ8BAf8E\nBAMCB4AwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMB0GA1UdDgQWBBRM\nO8Ak/HRgQ9j8iIK4xgONh+/W8DAfBgNVHSMEGDAWgBSNeT/nLC3Z+iRpVXVdvgpH\nlJRzwjArBgNVHREEJDAigiBteXNlcnZpY2UuaW50ZXJuYWwubXljb21wYW55Lm5l\ndDBMBgwrBgEEAYKkZMYoQAEEPDA6AgECBA9hdXRob3JpdHktYWRtaW4EJGQzMTc0\nMjM2LTE1YzEtNDEzOC04OTJkLTVlZDIzNDcxN2M5YTAKBggqhkjOPQQDAgNIADBF\nAiEA5kXI0dB6xMnEMAiwEigy0vYMHXYvX97BderaMFGdmSECIH2FQ/5A7RyxdkbE\nNVOdaxxFAW8YBCiyiKxnu0BzOM+C\n-----END CERTIFICATE-----\n",
  "subject": {
    "commonName": "myservice",
    "country": "",
    "organization": "",
    "organizationalUnit": "",
    "locality": "",
    "province": "",
    "street": "",
    "state": "",
    "email": ""
  },
  "sans": [
    {
      "type": "DNS",
      "value": "myservice.internal.mycompany.net"
    }
  ],
  "provisioner": {
    "id": "e5b0a6b4-3a2f-4a1e-9d8b-1f2c3d4e5f60",
    "name": "jamfpro-prod-users-bd8ff965",
    "type": "SCEP"
  }
}

Certificate expiring/expired event

{
  "category": "certificate-expiration",
  "authorityId": "5c780190-4e4e-4c5a-9331-50be29b28e21",
  "serialNumber": "204736770851791642908500119529647273613",
  "id": "4a0d055f-8ac2-463f-b090-0e940fadc0c3",
  "notBefore": "2022-08-01T20:48:20.000Z",
  "notAfter": "2022-08-01T20:54:20.000Z",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIICHzCCAcSgAwIBAgIRAJoG3iYtwd9xSbAsRjDMdo0wCgYIKoZIzj0EAwIwITEf\nMB0GA1UEAxMWSldLIFNBIEludGVybWVkaWF0ZSBDQTAeFw0yMjA4MDEyMDQ4MjBa\nFw0yMjA4MDEyMDU0MjBaMBQxEjAQBgNVBAMTCW15c2VydmljZTBZMBMGByqGSM49\nAgEGCCqGSM49AwEHA0IABNfWJtHDDXlvfiljmzzgNdzmmk5Xhxf84RiP9DShOXxI\nNgndPXYp7d49UCVKm3IrJ3HY/6WBh2g/cv0p2BQ3kUejgekwgeYwDgYDVR0PAQH/\nBAQDAgeAMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQU\nNgNvb8W9k/5/PHNQYx+xaQ45faQwHwYDVR0jBBgwFoAUjXk/5ywt2fokaVV1Xb4K\nR5SUc8IwKwYDVR0RBCQwIoIgbXlzZXJ2aWNlLmludGVybmFsLm15Y29tcGFueS5u\nZXQwSAYMKwYBBAGCpGTGKEABBDgwNgIBAQQEbmFtZQQrQ09pRDNLMzE1Mms3TW5Q\nNDR2eWlaLXNZaVphMmtSZU9fWFRNRG54RTB3VTAKBggqhkjOPQQDAgNJADBGAiEA\nuWabixlFwJif3+ypPdJax5xPwCPT+LxL2ETNP0RwGvICIQC/fdBn7b+W+sa9GSLx\nDFNysUCX39uO7F7XbAEJBRFa8A==\n-----END CERTIFICATE-----\n",
  "subject": {
    "commonName": "myservice",
    "country": "",
    "organization": "",
    "organizationalUnit": "",
    "locality": "",
    "province": "",
    "street": "",
    "state": "",
    "email": ""
  },
  "sans": [
    {
      "type": "DNS",
      "value": "myservice.internal.mycompany.net"
    }
  ],
  "provisioner": {
    "id": "e5b0a6b4-3a2f-4a1e-9d8b-1f2c3d4e5f60",
    "name": "jamfpro-prod-users-bd8ff965",
    "type": "SCEP"
  }
}

Certificate revocation event

Smallstep sends this event one time when a certificate is revoked from the dashboard, the API, or step-ca. It has no provisioner field.

{
  "category": "certificate-revocation",
  "authorityId": "5c780190-4e4e-4c5a-9331-50be29b28e21",
  "serialNumber": "3b25f3c5712ca4e01f8bfd74fa13cc2e",
  "id": "4f2f0c29-704a-46f8-8f90-f7f74675b169",
  "notBefore": "2022-08-01T20:36:51.000Z",
  "notAfter": "2022-08-01T20:42:51.000Z",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIICITCCAcegAwIBAgIQOyXzxXEspOAfi/10+hPMLjAKBggqhkjOPQQDAjAhMR8w\nHQYDVQQDExZKV0sgU0EgSW50ZXJtZWRpYXRlIENBMB4XDTIyMDgwMTIwMzY1MVoX\nDTIyMDgwMTIwNDI1MVowFDESMBAGA1UEAxMJbXlzZXJ2aWNlMFkwEwYHKoZIzj0C\nAQYIKoZIzj0DAQcDQgAEfDkIN/DlpolcxVqMu5iZ0zJqVlAXfasCJvGxwBJKpQdS\nZJOLsenrguwJJpLqNuj3icIhI6gFodqvLpNAcaJ/zKOB7TCB6jAOBgNVHQ8BAf8E\nBAMCB4AwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMB0GA1UdDgQWBBRM\nO8Ak/HRgQ9j8iIK4xgONh+/W8DAfBgNVHSMEGDAWgBSNeT/nLC3Z+iRpVXVdvgpH\nlJRzwjArBgNVHREEJDAigiBteXNlcnZpY2UuaW50ZXJuYWwubXljb21wYW55Lm5l\ndDBMBgwrBgEEAYKkZMYoQAEEPDA6AgECBA9hdXRob3JpdHktYWRtaW4EJGQzMTc0\nMjM2LTE1YzEtNDEzOC04OTJkLTVlZDIzNDcxN2M5YTAKBggqhkjOPQQDAgNIADBF\nAiEA5kXI0dB6xMnEMAiwEigy0vYMHXYvX97BderaMFGdmSECIH2FQ/5A7RyxdkbE\nNVOdaxxFAW8YBCiyiKxnu0BzOM+C\n-----END CERTIFICATE-----\n",
  "subject": {
    "commonName": "myservice",
    "country": "",
    "organization": "",
    "organizationalUnit": "",
    "locality": "",
    "province": "",
    "street": "",
    "state": "",
    "email": ""
  },
  "sans": [
    {
      "type": "DNS",
      "value": "myservice.internal.mycompany.net"
    }
  ],
  "revokedAt": "2022-08-01T20:39:12.000Z",
  "reasonCode": "KEY_COMPROMISE",
  "reason": "Private key found in a public repository"
}

Where:

Parameter	Description
category	The specific webhook event type.
authorityId	The ID of the certificate authority responsible for the issuance of the created, about to expire, already expired, or revoked certificate.
serialNumber	The serial number of the certificate
id	The Smallstep UUID of the certificate
notBefore	The time before which the certificate is ineligible for use.
notAfter	The time after which the certificate will no longer be valid (i.e, expiration time)
certificate	The PEM encoded format of the certificate
subject	An object containing details of the entity that the certificate was issued for.
sans	An array of the details of the certificate's subject alternative names
provisioner	An object identifying the provisioner that issued the certificate, with `id`, `name`, and `type`. The `name` is omitted when it cannot be resolved. Revocation events do not include this field.
revokedAt	Revocation events only. The time at which the certificate was revoked.
reasonCode	Revocation events only. The revocation reason code. One of `UNSPECIFIED`, `KEY_COMPROMISE`, `CA_COMPROMISE`, `AFFILIATION_CHANGED`, `SUPERSEDED`, `CESSATION_OF_OPERATION`, `CERTIFICATE_HOLD`, `PRIVILEGE_WITHDRAWN`, or `AA_COMPROMISE`. If no reason code was given, the value is `UNSPECIFIED`.
reason	Revocation events only. The revocation reason text, if one was given.

Deleting webhook events

If you no longer have need for a webhook and wish to delete it:

Go to Settings > Webhooks
Click on the webhook's name
Click on Unregister this webhook as shown below:

Last updated on October 19, 2026

Introducing

Device Identity

Ensure that only company-owned devices can access your enterprise's most sensitive resources.

Try now