Webhook Events

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

certificate creation, and certificate expirations 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 or expires.
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`, or `certificate-expiration`.
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"
    }
  ]
}

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

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, or already expired 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

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:

Webhook Events

Webhook Events

Webhook Event Types

Using Webhook Events

Webhook Events Response Formats

Deleting Webhook Events

Device Identity