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

  1. A service publishes a domain event.
  2. Lamassu evaluates the subscriptions associated with that event type.
  3. Each subscription's filter decides whether it should be notified.
  4. 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 POST or PUT.

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_options requires header and key.
  • jwt_options requires oidc_client_id, oidc_client_secret and an absolute http or https oidc_well_known.
  • mtls_options requires cert_content and key_content as 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, warn or error; info is 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-Key by default), OIDC Client Credentials (Client ID, Client Secret and Well-Known URL) or Mutual 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 warning Unencrypted 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_verify is enforced as false — including when it is set to true — so self-signed or otherwise untrusted receivers fail delivery.
  • Redirects are not followed. A 3xx response fails with unexpected status code: <n>: redirects are not followed. Configure webhook_url with the final absolute http or https URL: an http:// address that an ingress redirects to https:// stops working.
  • Calls are bounded. A call defaults to a 10 second timeout; a configured call_timeout is 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.header may not use names that the platform or receiving services trust — for example X-Principal-Id, X-Request-Id, Host, Content-Type or Forwarded — and no name may start with X-Forwarded-, X-Envoy- or X-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.reissue and ca.delete.
  • Certificates: ca.sign.certificate and certificate.delete.
  • Profiles: profile.issuance.create, profile.issuance.update and profile.issuance.delete.
  • Enrollment: dms.create, dms.update, dms.enroll and dms.reenroll.
  • Devices: device.create, device.identity.update and device.status.update.
  • Validation: va.role.crl.create, va.crl-settings.init, va.crl-settings.update, va.crl-settings.finalize, va.crl-settings.archive and va.crl-settings.delete.
  • Keys: kms.create, kms.import, kms.sign and kms.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.

On this page