About webhook notifications¶

Certificate Manager - SaaS can send webhook notifications when certificates are nearing expiration. This allows you to integrate certificate expiration alerts into your existing monitoring or incident management systems.

When a certificate crosses one of the predefined expiration thresholds, Certificate Manager - SaaS generates an expiration event and delivers it to any configured webhook connectors. The event payload follows a normalized event structure.

Webhook network origin¶

Webhook deliveries are sent from CyberArk Identity Security Platform (AWS), not from VSatellite instances. Webhooks are sent from specific CyberArk public NAT IP addresses, which your network administrator must add to the allowlist in your firewall to ensure successful delivery. If these IP addresses are not allowed through your firewall, webhook deliveries might fail with timeouts or connection errors. During creation of the connector, Certificate Manager - SaaS performs a reachability check from these IP addresses.

These IP addresses are subject to change with release or infrastructure updates. New IP addresses may also be added for different global regions. Updates to this list will also be communicated through our What's New page.

Network requirements for webhook endpoints¶

To ensure successful delivery of webhook notifications, your webhook endpoint must be accessible from the public internet over HTTPS (port 443). Internal-only or private endpoints are not supported.

When you create a webhook connector in Certificate Manager - SaaS, the system performs a reachability test by sending a test POST. This verifies that your webhook endpoint is accessible from the public internet. If the test fails, you must resolve any network issues before proceeding. The actual test payload is:

{
  "events": [
    { "message": "### VAAS: TESTING CONNECTION... OK ###" }
  ]
}

Supported authentication for webhook endpoints¶

Certificate Manager - SaaS supports the use of a single Authorization header when delivering webhook notifications. Most webhook receivers support one of the following standard Authorization header formats:

• Authorization: Bearer <token>
• Authorization: Basic <base64 credentials>
• Authorization: Splunk <token>

If you configure a secret for the connector, Certificate Manager - SaaS also includes an HMAC signature:

• VaaS-Signature: <base64url-encoded HMAC>

Every webhook request also includes the following headers:

• Content-Type: application/json
• VaaS-Timestamp: <unix timestamp in seconds>

If your webhook endpoint requires additional headers or a custom content type, it might not be compatible with generic webhooks.

Webhook payload structure¶

Generic webhooks receive a single event wrapped in an events array:

{
  "events": [
    {
        "eventName": "string",
        "eventType": "string",
        "message": "string",
        "criticality": integer,
        "createdAt": "ISO 8601 date-time string"
    }
  ]
}

These fields are included in the webhook payload:

• eventType: The type of event, which is CertificateExpiration for expiring certificates.
• eventName: A human-readable name for the event.
• message: A descriptive message about the expiring certificate, including its common name and expiration date. All certificate-specific details appear in this message. Extract them via parsing if you need specific fields.
• criticality: An integer representing the severity of the event. (0 = info, 1 = warning).
• createdAt: The timestamp when the event was created, in ISO 8601 format.

Certificate expiration notifications are delivered one event per webhook request.

The following example shows a certificate expiration event as it appears in an actual webhook delivery.

{
  "events": [
    {
        "eventType": "CertificateExpiration",
        "eventName": "Certificate Expiration",
        "message": "Certificate api.example.com expires on 2025-02-01T00:00:00Z",
        "criticality": 1,
        "createdAt": "2025-01-15T12:45:00Z"
    }
  ]
}

Microsoft Teams webhooks¶

Microsoft Teams connectors don't receive the generic JSON envelope. Instead, Certificate Manager - SaaS automatically converts the normalized event into a Microsoft Teams Adaptive Card. The card includes the same event details—name, type, message, and timestamp—formatted for Teams display.

Teams webhooks are useful when event notifications need to appear directly in collaborative channels.

Webhook delivery behavior¶

Certificate Manager - SaaS attempts to deliver each certificate expiration event to the configured webhook endpoint as an HTTP POST request.

If delivery fails due to network errors, endpoint unavailability, or non-successful HTTP responses, Certificate Manager - SaaS retries delivery for up to 24 hours. During this period, the platform continues attempting to deliver the event without user intervention.

If delivery continues to fail for the full retry period, the webhook connector is automatically disabled. After a connector is disabled, no additional events are delivered until the connector is recreated.

Additional resources¶

For more information on setting up certificate expiration webhooks, see our guide in Dev Central.

Related links¶

• Notifications overview
• Set up certificate expiration notifications
• Control Plane: Receive webhook notifications