Webhook Integration

• Name (required): The name of the webhook
• URL (required): The URL of the webhook. You can use template variables in the URL for dynamic values (see template variables section below)
• HTTP Method: The HTTP method to use when sending the webhook. Default is POST
• Headers: Additional headers to send with the webhook. If you are sending a POST request, Content-Type header is added by default with the value application/json. You can add more headers by clicking on the Add Header button.
• Body Template (optional): If you would like to send a custom body with the webhook, you can use the body template. Leave empty to use the default JSON payload. You can use template variables in your webhook body (see template variables section below).
• Folder Location: The filesystem folder where the webhook is saved. Manual webhooks default to /webhooks/default/, and custom team folders must live under /webhooks/.

​

Kubernetes-managed webhooks

apiVersion: observability.metoro.io/v1alpha1
kind: MetoroWebhook
metadata:
  name: rootly-critical-alerts
  namespace: payments
spec:
  displayName: Rootly Critical Alerts
  url: https://api.rootly.com/webhooks
  method: POST
  headers:
    Content-Type: application/json
  headersFrom:
    Authorization:
      secretKeyRef:
        name: rootly-webhook
        key: authorization
  body: |
    {
      "alert": "$alert_name",
      "state": "$alert_state",
      "message": "$alert_message"
    }

​

How it works

• The MetoroWebhook CRD is installed by the Metoro exporter chart on every monitored cluster, so it is available on both Metoro cloud and on-prem. The base resource ships with metoro-exporter chart version 0.476.0 or later (Metoro cloud) and metoro-exporter-onprem 11.0.0 or later; the headersFrom/bodyFrom Secret references require metoro-exporter 0.477.0 or later (or the latest 11.x on-prem exporter chart). On an older chart the fields are silently dropped by the Kubernetes API server, so upgrade the exporter chart before using them.
• Most MetoroWebhook creates, spec updates, and deletions appear in Metoro in about 30 seconds; allow up to one minute for the exporter and sync workflow to process a change.
• If the exporter is configured with a METORO_K8S_RESOURCES allowlist restricting which resources it watches, the list must include metoro-webhook (or another MetoroWebhook alias); otherwise applied webhooks are never discovered.
• List synced webhooks with kubectl get metorowebhooks -A (short names: mw, mwebhook).

​

Referencing Kubernetes Secrets

• References always resolve in the webhook’s own namespace. A secretKeyRef carries only name and key; cross-namespace references are not representable.
• Values are resolved at delivery time. The Metoro exporter mirrors just the referenced Secret keys to an encrypted store; the CRD, its exported snapshot, the integration record, the UI, and delivery failure messages never contain the values.
• Rotation needs no CRD change. The exporter re-syncs referenced Secrets every 60 seconds, so an edited Secret takes effect on the next delivery within about a minute.
• Deleting a Secret revokes it. The mirrored values are removed on the next sync and deliveries fail (rather than sending stale credentials) until the Secret is recreated.

​

Enabling Secret syncing

exporter:
  secretRefs:
    enabled: true
    # Namespaces beyond the exporter's own whose Secrets may be referenced.
    namespaces: []
    # Or grant cluster-wide access instead of per-namespace Roles.
    global: false

​

Spec reference

​

End-to-end example

apiVersion: v1
kind: Secret
metadata:
  name: webhook-site-test
  namespace: metoro
type: Opaque
stringData:
  authorization: Bearer my-test-token
  body: '{"alert":"$alert_name","state":"$alert_state","source":"secretKeyRef bodyFrom"}'
---
apiVersion: observability.metoro.io/v1alpha1
kind: MetoroWebhook
metadata:
  name: webhook-site-test
  namespace: metoro
spec:
  displayName: Webhook Site Test
  url: https://webhook.site/<your-inbox-uuid>
  method: POST
  headers:
    Content-Type: application/json
  headersFrom:
    Authorization:
      secretKeyRef:
        name: webhook-site-test
        key: authorization
  bodyFrom:
    secretKeyRef:
      name: webhook-site-test
      key: body
---
apiVersion: observability.metoro.io/v1alpha1
kind: MetoroAlert
metadata:
  name: webhook-delivery-test
  namespace: metoro
spec:
  displayName: Webhook Delivery Test (temporary)
  description: Fires immediately to test webhook delivery. Safe to delete.
  timeseries:
    evaluationRules:
      - name: Condition
        type: static
        actions:
          - type: webhook
            webhookDestination:
              uuid: "kubernetes-managed.<cluster>.metoro.webhook-site-test"
              name: Webhook Site Test
        static:
          operators:
            - operator: greaterThan
              threshold: -1
          persistenceSettings:
            datapointsToAlarm: 1
            datapointsInEvaluationWindow: 1
            missingDatapointBehavior: notBreaching
    expression:
      metoroQLTimeseries:
        query: count(traces)
        bucketSize: 60

POST /<your-inbox-uuid>
Authorization: Bearer my-test-token
Content-Type: application/json

{"alert":"Webhook Delivery Test (temporary)","state":"firing","source":"secretKeyRef bodyFrom"}

​

Validation and failure modes

• A MetoroWebhook that passes the CRD schema but fails sync-time validation (a header in both headers and headersFrom, Content-Type in headersFrom, both body and bodyFrom set, or a malformed secretKeyRef) is skipped and does not create or update an integration. The reason is written into your own logs as an error record in the metoro-internal environment under the service metoro-webhook-sync, so you can find and alert on it.
• If a reference cannot be resolved at delivery time, the webhook is not sent — a request delivered without its Authorization header is worse than one not delivered. The delivery failure names the Secret and a reason (missing_secret, missing_key, …) but never a value.
• missing_secret/missing_key are retried across the exporter’s sync interval, which covers the window where a freshly applied webhook fires before its Secret has been mirrored (typically the webhook’s first minute of existence).
• If Secret syncing is not enabled on the exporter (or the namespace is out of scope), references never resolve and deliveries fail with missing_secret; enable exporter.secretRefs as above.

​

Exporting an existing webhook

​

Template Variables

​

Alert variables

• $alert_name: The name of the alert
• $alert_description: The description of the alert
• $alert_uuid: The UUID of the alert definition
• $alert_fire_uuid: The UUID of the specific alert fire instance
• $alert_state: The state of the alert (either “firing” or “resolved”)
• $deep_link: Direct link to view the alert details in Metoro
• $environment: [Deprecated - use $attributes instead] Environment context of the alert. It’s set for Kubernetes and Log alerts only or if the alert has a group by with environment
• $service: [Deprecated - use $attributes instead] The service associated with the alert. It’s set for Kubernetes and Log alerts only or if the alert has a group by with service.name/service_name/client.service.name/server.service.name.
• $fired_at: Unix Timestamp when alert was fired
• $resolved_at: Unix Timestamp when alert was resolved/recovered.
• $breaching_datapoint_value: The last metric/trace value that triggered the alert. It’s set for Trace and Metric alerts only.
• $breaching_datapoint_time: Unix Timestamp of the last breaching value. It’s set for Trace and Metric alerts only.
• $metric_name: Name of the metric that triggered the alert. It’s set for Trace and Metric alerts only.
• $attributes: List of attribute key and value pairs (in key: value format) for which the alert is firing. Only set when you use a group by in your alert.

​

AI SRE (Guardian) notification variables

• $title: The notification title, as plain text
• $message: The notification message, as plain text
• $type: The specific event type (see the table below) — use this to distinguish notifications on your end
• $deep_link: Direct link to view the relevant page in Metoro (may be empty for some notification types where the link is embedded in the message instead)

​

Default Guardian webhook payload

{
  "id": "8f2c1d34-2d9a-4b4a-bb0e-6a0d7c1f5e55",
  "type": "anomalyDetected",
  "timestamp": "2026-07-29T10:12:03Z",
  "title": "5XX rate anomaly detected for `checkout-service` in `prod-eu` ...",
  "message": "5XX rate anomaly detected for `checkout-service` in `prod-eu` ...",
  "data": {
    "deepLink": "https://us-east.metoro.io/events/inbox",
    "serviceName": "checkout-service",
    "environment": "prod-eu",
    "namespace": "shop",
    "anomalyType": "5xx_rate_increase",
    "zScore": 4.12,
    "currentValue": 8.4,
    "baselineValue": 1.1
  }
}

• id is the UUID of the underlying event — stable across delivery retries, use it for deduplication.
• type determines the shape of the typed data object; the full schema for every event type is in the Webhook Events section of the API reference (starting at deployment rollout detected).

​

Examples

​

URL Examples

https://api.example.com/webhook?alert=$alert_name&value=$breaching_datapoint_value
https://api.example.com/alerts/$alert_uuid/fire/$alert_fire_uuid
https://api.example.com/webhook?state=$alert_state&service=$service

​

Body Template Examples

1. JSON format:

{ 
  "alert": "$alert_name", 
  "alert_uuid": "$alert_uuid",
  "alert_fire_uuid": "$alert_fire_uuid",
  "state": "$alert_state",
  "value": "$breaching_datapoint_value",
  "deep_link": "$deep_link" 
}

2. Plain text format:

Alert $alert_name ($alert_uuid) is $alert_state with value $breaching_datapoint_value

3. XML format:

<alert>
  <name>$alert_name</name>
  <uuid>$alert_uuid</uuid>
  <fire_uuid>$alert_fire_uuid</fire_uuid>
  <state>$alert_state</state>
  <value>$breaching_datapoint_value</value>
</alert>