Webhook Events

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:

image

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:

ParameterDescription
categoryThe webhook event type. One of ssh-session, certificate-request, or certificate-expiration.
hostnameThe name of the registered host
usernameThe posix username of the user responsible for the ssh session
idThe smallstep ssh session id
timestampThe time at which the event occurred
typeThe 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:

ParameterDescription
categoryThe specific webhook event type.
authorityIdThe ID of the certificate authority responsible for the issuance of the created, about to expire, or already expired certificate.
serialNumberThe serial number of the certificate
idThe Smallstep UUID of the certificate
notBeforeThe time before which the certificate is ineligible for use.
notAfterThe time after which the certificate will no longer be valid (i.e, expiration time)
certificateThe PEM encoded format of the certificate
subjectAn object containing details of the entity that the certificate was issued for.
sansAn 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:

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

image