Skip to main content
A webhook channel on a certificate alert sends an HTTP POST request to your endpoint whenever the alert fires. Use a webhook to connect certificate alerts to your own systems or to services Infisical doesn’t support directly.
Webhook channels are available under Infisical’s Enterprise plan. If you’re self-hosting Infisical, contact [email protected] to purchase an enterprise license.

​
Prerequisites

  • The Certificate Management Admin role to create an organization-wide alert, or the Admin application role to create an application alert
  • An HTTPS endpoint that accepts POST requests

​
Create the alert

1
Open the alert form:
  • For an organization-wide alert, go to Certificate Manager > Settings, select the Alerts tab, then select Create Alert
  • For an application alert, go to Certificate Manager > Applications and select your application, then select the Settings tab and select Create Alert in the Alerts section
2
Select the Alert Type, then enter an Alert Name and an optional Description. An application can have one alert for each event, so to notify more places about the same event, add more channels to that alert.
3
For an expiration alert, enter Alert Before as a number and a unit. For example: 30d or 2w, up to 365 days.
To get a reminder every day, turn on Repeat daily until expiry. Otherwise, the alert repeats on a schedule based on Alert Before.
Select Continue.
4
For an organization-wide alert, on the Filters step, optionally select Add Filter to narrow the certificates the alert covers, then select Continue. Application alerts and signer certificate expiration alerts skip this step.
To add this channel to an existing alert instead, edit the alert and go to its Channels step.
On the Channels step, add the webhook channel:
1
Select Add Channel > Webhook and enter your endpoint’s URL. The URL must use HTTPS.
2
If your endpoint requires authentication, under Authentication, select Bearer Token, Basic Auth, or API Key, and enter the credentials it expects.
3
Optionally, select Add Signing Secret and enter a secret, so your endpoint can verify the signature of each request.
4
Optionally, select Add Header to send custom headers with each request.
5
Optionally, select Send test to send a test request to your endpoint.
6
Select Continue, check the Review step, and select Create Alert.
Your alert is set up. Infisical sends a POST request to your endpoint whenever the alert fires.

​
Authentication

A channel can have one authentication method, which Infisical sends as a header on each request: For an Authorization scheme other than Bearer, such as GenieKey <key>, select API Key, enter Authorization as the header name, and enter the full value, including the scheme. Infisical doesn’t show saved credentials again. When you edit the channel, leave a field blank to keep its saved value. If you change the URL, enter the credentials again, because Infisical only sends them to the URL they were saved with.

​
Custom headers

Infisical sends custom headers with each request, such as an X-Env header your endpoint uses to route alerts:
  • Anyone who can view the alert can see header values, so put credentials, including any Authorization header, in authentication
  • A channel can have up to 20 custom headers, and header names, values, and authentication credentials can total up to 4,096 characters
  • Infisical sets Content-Type, Content-Length, Transfer-Encoding, Connection, Host, and x-infisical-signature itself, so you can’t add them

​
Webhook event types

Each request is a CloudEvents JSON payload. The type field names the event, and application alerts and organization-wide alerts use different values: The subject field is the same value without the com.infisical. prefix.

​
Webhook payload format

data.items lists the certificates the alert fired for. Each item has the certificate’s ID, a title (its common name, or its first SAN or serial number when it has none), a one-line summary, a severity, and a list of display fields. To act on a certificate in code, read resource instead of fields: it holds the certificate’s typed values, with ISO 8601 dates and the raw revocation reason code. An expiration request can include several certificates, and data.alert.condition holds the alert’s lead time as you entered it, such as 30d or 2w. Issuance, renewal, and revocation requests include the one certificate the event was about. To find out which kind of alert sent a request, read data.alert.resourceType:
  • cert-manager.application: an application alert, with the application’s ID in data.alert.resourceId
  • cert-manager: an organization-wide alert
  • cert-manager.signer: a signer certificate expiration alert, whose items list the signers in resource.signerIds and resource.signerNames (only the selected signers, if the alert has a Signers filter)
Alerts created before certificate alerts moved to applications keep sending the older com.infisical.pki.certificate.* event types with a data.certificates list. If one endpoint receives both, check the type field to tell them apart.

​
Webhook signature verification

If you set a signing secret, each request carries an x-infisical-signature header:

​
Verify the signature

  1. Read the timestamp and the signature from the header
  2. Join the timestamp and the raw request body with a dot: {timestamp}.{raw-body}
  3. Compute the HMAC SHA256 of that string with your signing secret
  4. Compare the result with the signature from the header