Alerts and subscriptions
Send PKI events to people and external systems.
Subscriptions turn Lamassu events into actionable notifications. You can alert a team, feed an incident system or trigger an automation when a CA, certificate or device changes.
How it works
- A service publishes a domain event.
- Lamassu evaluates the subscriptions associated with that event type.
- Each subscription's filter decides whether it should be notified.
- Lamassu delivers the event to the configured channel.
The event inventory shows when each type was last observed, how many times it has occurred and how many subscriptions it has. You can expand an event to inspect an example of its JSON payload before creating the filter.
Available channels
- Email sends alerts to a person or an operational list. It only requires the destination address. Event content is rendered as HTML-escaped text, never as markup.
- Microsoft Teams posts the notification to a channel through its webhook URL.
- Webhook delivers the event to an automation, SIEM or incident system via
POSTorPUT.
The Microsoft Teams and Webhook channels accept an optional http_client block that authenticates the call to the receiver. auth_mode selects noauth (the default), apikey, jwt or mtls; each mode requires its own options:
apikey_optionsrequiresheaderandkey.jwt_optionsrequiresoidc_client_id,oidc_client_secretand an absolutehttporhttpsoidc_well_known.mtls_optionsrequirescert_contentandkey_contentas Base64-encoded PEM, like certificates elsewhere in the API; plain PEM is also accepted. Values that reference files on the server are rejected, and the pair must decode to a matching certificate and private key.
The alerts API reference documents the full http_client schema.
Create a subscription
Choose the event
Open Alerts, locate the event type and select Subscribe. Review the latest JSON example to identify the fields you will need to filter on.
Configure the destination
Select Email, Microsoft Teams or Webhook and enter the channel details.
Limit the notifications
Add a filter if you don't want to receive every instance of the event.
- None notifies all instances of the event.
- JSON Path evaluates one or more specific fields.
- JSON Schema accepts only payloads with a particular structure.
- JavaScript lets you express custom logic. Each filter runs for at most 100 milliseconds; a filter that exceeds this limit fails the condition and the notification is skipped with the error
javascript filter execution timed out.
For example, function (event) { return event.data.status == "NO_IDENTITY"; } limits a subscription to devices without an identity.
The console evaluates the filter against the JSON shown in the Input Event editor, which is prefilled with the latest event, and reports whether it matches. For JSON Path and JavaScript filters, it shows The filter matches this Cloud Event or The filter does not match this Cloud Event. JSON Path expressions are evaluated against the full Cloud Event, so the default $.data selects the event's data field, and the expression must start with $.
Review and activate
Check the event, channel and filter in the summary. Select Confirm Subscription to start delivery.
Configure the webhook HTTP client
The Webhook and Microsoft Teams channels show this configuration in the subscribe form, at the channel step, and again when editing a subscription; Email does not use it. The fields map to the optional http_client block described above:
- Log Level selects
debug,info,warnorerror;infois the default. - Call Timeout defaults to 10 seconds. The console rejects a value above 30 seconds with
Webhook timeout must be at most 30s.; the API clamps the same value to the cap instead (see Calls are bounded). - There is no TLS-verification switch for these channels, because the service always verifies the receiver certificate (see TLS is always verified).
- HTTP Authentication selects
No Authentication(the default),API Key(API key value and Header Name,X-API-Keyby default),OIDC Client Credentials(Client ID, Client Secret and Well-Known URL) orMutual TLS(Client Certificate and Client Private Key pasted as PEM). A stored private key stays hidden until you select Show. - A
http://URL shows the console warningUnencrypted HTTP connection(see the Credentials over http:// callout below).
The form validates inline against the same delivery rules: the webhook URL and the OIDC Well-Known URL must be absolute http or https URLs, an API-key header may not use a reserved name, and the mTLS certificate and key must be PEM content, not file paths.
The summary in the Confirm step shows the authentication as None, OIDC client credentials, API key or Mutual TLS. The subscription details show the authentication, the API key header name (never the value), the OIDC issuer URL, mTLS as Configured and a fixed TLS verification: Verified row. The API key, client secret and private key are not shown in the subscription details.
Webhook delivery rules
Notifications delivered through the Microsoft Teams and Webhook channels follow a fixed HTTP policy:
- TLS is always verified. The receiver certificate is checked against the system trust store.
insecure_skip_verifyis enforced asfalse— including when it is set totrue— so self-signed or otherwise untrusted receivers fail delivery. - Redirects are not followed. A
3xxresponse fails withunexpected status code: <n>: redirects are not followed. Configurewebhook_urlwith the final absolutehttporhttpsURL: anhttp://address that an ingress redirects tohttps://stops working. - Calls are bounded. A call defaults to a 10 second timeout; a configured
call_timeoutis capped at 30 seconds. Values above the cap are clamped, not rejected. - The response body is ignored. Delivery checks the status code only, so the receiver may answer with any body.
- API-key headers are restricted. A custom
apikey_options.headermay not use names that the platform or receiving services trust — for exampleX-Principal-Id,X-Request-Id,Host,Content-TypeorForwarded— and no name may start withX-Forwarded-,X-Envoy-orX-Lms-. Comparisons are case-insensitive. - Invalid configurations are rejected at subscribe time. A channel configuration that would fail on every delivery returns HTTP 400 with a body that starts with
struct validation error:, and the subscription is not created.
Credentials over http://
Credentials are sent regardless of the URL scheme. With an http:// webhook_url, the API key or bearer token travels in cleartext and mTLS has no effect. Prefer https:// for webhook_url, oidc_well_known and the token endpoint it advertises.
Manage a subscription
Open an existing subscription to review its destination and filter, modify the configuration or select Unsubscribe. Remove subscriptions that no longer have an operational owner to avoid ignored deliveries or stale endpoints.
Subscriptions created with older console versions may store the webhook target under url and method instead of webhook_url and webhook_method. The service delivers only through webhook_url and webhook_method, so such a subscription does not deliver even though the subscription details show the stored target. Open the subscription and save it again: the edit form prefills the stored target, and saving rewrites the channel configuration in the current layout.
Event families
- Authorities:
ca.create,ca.import,ca.reissueandca.delete. - Certificates:
ca.sign.certificateandcertificate.delete. - Profiles:
profile.issuance.create,profile.issuance.updateandprofile.issuance.delete. - Enrollment:
dms.create,dms.update,dms.enrollanddms.reenroll. - Devices:
device.create,device.identity.updateanddevice.status.update. - Validation:
va.role.crl.create,va.crl-settings.init,va.crl-settings.update,va.crl-settings.finalize,va.crl-settings.archiveandva.crl-settings.delete. - Keys:
kms.create,kms.import,kms.signandkms.delete.
Use the catalog shown in the console as the source for the types available in your deployed version.
Since 4.0.0, va.crl-settings.init and va.crl-settings.update carry the CRL settings of a CA (ca_id) and replace va.role.crl.init and va.role.update. The upgrade migration renames the types of existing subscriptions automatically, but it does not rewrite their conditions: review filters that read the old payload or the old crl/<ski> subject, including filters for va.role.crl.create (see 3.8.0 to 4.0.0).
The VA also publishes va.crl-settings.finalize when a CA is revoked permanently or expires, va.crl-settings.archive when the CA is deleted, and va.crl-settings.delete when archived settings are removed.