Events

Events power alerting for certificate lifecycle activities. Used to help administrators operate the Smallstep Platform, Events can be generated and surfaced via standard mechanisms. Events are a feature of the commercial Smallstep Certificate Manager offering.

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