Skip to content

Webhook Delivery

CertifyClouds delivers alert notifications via webhook to four built-in receiver shapes: Slack, Microsoft Teams, PagerDuty Events API v2, and a generic JSON for custom endpoints.

The exact payload your endpoint receives depends on which receiver type you chose when creating the alert rule. The shapes below are the ones receivers genuinely need to parse - unlike the rest of the REST API, these are the contract on the wire to your endpoint, so they're documented here in full.

Configuration is in the UI

Alert rule creation, channel selection, delivery testing, and retry history are managed in the Settings → Alerts dashboard. The REST endpoints for automation are catalogued in Endpoints overview and the exact request / response shapes are in your deployment's /docs.

Receiver formats

Slack (and Discord)

Compatible with Slack Incoming Webhooks. Discord webhooks also accept the Slack format if the URL ends in /slack.

{
  "attachments": [
    {
      "color": "#EF4444",
      "title": "Secret Expiring Alert",
      "text": "Found 3 secrets expiring within 30 days",
      "footer": "CertifyClouds",
      "ts": 1702569600,
      "fields": [
        { "title": "Vault", "value": "kv-production", "short": true },
        { "title": "Items", "value": "api-key, db-password, cert-primary", "short": true }
      ]
    }
  ]
}

Color is hex #RRGGBB; severity → colour mapping is internal and may evolve, but red / orange / green / blue correspond to error / warning / success / info respectively.

Microsoft Teams

Compatible with Microsoft Teams Incoming Webhooks (legacy Connectors and Workflows that consume MessageCard).

{
  "@type": "MessageCard",
  "@context": "https://schema.org/extensions",
  "summary": "Secret Expiring Alert",
  "themeColor": "EF4444",
  "title": "Secret Expiring Alert",
  "text": "Found 3 secrets expiring within 30 days",
  "sections": [
    {
      "facts": [
        { "name": "Vault", "value": "kv-production" },
        { "name": "Items", "value": "api-key, db-password, cert-primary" }
      ]
    }
  ]
}

themeColor is the hex code without the #.

PagerDuty (Events API v2)

Native PagerDuty support - give the alert rule your PagerDuty Integration Key (the routing_key) when configuring the rule; CertifyClouds posts to the fixed events.pagerduty.com/v2/enqueue endpoint and PagerDuty handles the rest.

Payload conforms to the PagerDuty Events API v2 contract; CertifyClouds populates:

  • routing_key - your Integration Key
  • event_action - trigger or resolve
  • dedup_key - derived from the vault + asset + rule so the same recurring violation collapses to one incident across retries rather than multiplying
  • payload.summary - short alert headline
  • payload.severity - critical / error / warning / info, mapped from CertifyClouds severities
  • payload.source - CertifyClouds plus the deployment identifier
  • payload.custom_details - context fields (vault, items, counts)

Success events (rotation completed, scan completed) do not page on-call by default; only failure / violation events fire. To override, contact support.

Generic JSON

For custom integrations - scripts, low-code platforms, observability pipelines, etc.

{
  "title": "Secrets Expiring Soon",
  "message": "Found 5 secrets expiring within 30 days",
  "color": "#F97316",
  "timestamp": "2026-05-20T12:00:00+00:00",
  "source": "CertifyClouds",
  "fields": [
    { "title": "kv-production", "value": "api-key (expires 2026-06-20)" },
    { "title": "kv-staging", "value": "service-account (expires 2026-07-02)" }
  ]
}

timestamp is ISO 8601 with explicit UTC offset. fields is optional.

Delivery + retry behaviour

  • Each webhook request has a 10 second timeout.
  • 2xx responses are treated as success and not retried.
  • 4xx responses (except 408 / 429) are treated as a permanent client error and not retried - fix the endpoint or the rule.
  • 5xx responses, 408 / 429, network timeouts, and connection errors are retried with exponential backoff. Exact attempt-count and backoff cadence may evolve between releases; the audit log records every delivery attempt with status code and error.

If your endpoint is slow, accept fast (e.g. return 202) and process asynchronously. The Alerts dashboard surfaces a per-rule delivery history so you can spot persistent failures without grepping logs.

Wiring it up

Receiver Where to get the URL / key Notes
Slack Slack admin → Apps → Incoming Webhooks → install for the target channel Free tier supports webhooks
Discord Server settings → Integrations → Webhooks → New webhook → copy URL, append /slack Use the Slack receiver type
Microsoft Teams Channel → Manage → Connectors → Incoming Webhook → configure → copy URL MessageCard format; modern Workflow templates also work
PagerDuty Service → Integrations → Add → Events API v2 → copy the Integration Key Use the PagerDuty receiver type and paste the routing key; no URL needed
Custom Your endpoint URL Accept POST with Content-Type: application/json

Troubleshooting

Webhook not received

  • Verify the URL or integration key in the Alerts dashboard
  • Confirm the receiver accepts POST with JSON content type
  • Check outbound firewall rules permit CertifyClouds to reach the endpoint
  • Review the alert rule's delivery history for the last error

Wrong format on receiver

  • The receiver type set in CertifyClouds must match the endpoint's expectations (Slack format to a Slack URL, etc.)

Duplicate notifications

  • Multiple rules may be configured for overlapping triggers
  • Severity threshold overlap can cause one underlying event to fire more than one rule