Webhooks

Metaplane supports sending incident alerts to 3rd party systems via webhooks.

Setup

First, navigate to the alerts settings page. Scroll to the bottom of the page and find the option to add a new webhook alert destination.

Fill out the form and then click "Add destination."

Verify

You can have Metaplane send you a sample incident by using the actions menu to "Verify" the webhook alert destination.

Refer to the alert routing docs to learn more about how to route specific incidents to your webhook.

Payload

You can expect the payload to match this schema:

{
    id: string;
    createdAt: string;
    updatedAt: string;
    idempotencyId: string;
    status: "resolved" | "opened";
    acknowledged: boolean;
    acknowledgedAt: string;
    incidentUrl: string;
    affectedMonitors: Array<{
        id: string;
        monitor: {
            id: string;
            type: string;
            name: string;
            entityType: string;
            absolutePath: string;
        };
        linkedAt: string;
        resolvedAt: string | null;
        group: Array<{
            name: string;
            value: string;
        }> | null;
        connections: Array<{
        	id: string;
          name: string | null;
          type: string;
        }>
    }>;
}

Delivery semantics

The webhook systems conforms to atleast-once delivery semantics. This effectively means that you may receive the exact same event more than once — your 3rd party service should be idempotent so that this detail doesn't cause issues.

One straight-forward way of identifying duplicate payloads is by using the idempotencyId. Multiple payloads with the same idempotencyId will be identical. However, multiple payloads with different idempotencyIds aren't guaranteed to be different. That is, it's possible that 2 payloads have different idempotencyIds while the the rest of the payload content is the same.

affectedMonitors

The items within affectedMonitors represent monitors that have been implicated in the incident. Currently, you can expect that only monitors are affected.

Affected monitors may have a group value. If the group value is not null then it'll be an array of key-value pairs that identify a specific group. The group property will only be populated if the alerting monitor is a Group By monitor.

Example payload

  "id": "26345",
  "createdAt": "2024-05-03T13:43:56.243Z",
  "updatedAt": "2024-05-03T13:43:56.243Z",
  "idempotencyId": "MjYzNDUtMjAyNC0wNS0wM1QxMzo0Mzo1Ni4yNDNa",
  "status": "opened",
  "acknowledged": false,
  "acknowledgedAt": "2024-05-03T13:43:56.243Z",
  "incidentUrl": "https://app.metaplane.dev/incident/26345",
  "affectedMonitors": [
    {
      "id": "26312",
      "linkedAt": "2024-05-03T13:43:56.315Z",
      "resolvedAt": null,
      "monitor": {
        "id": "018f3eb0-d994-7a34-a956-92a30a439157",
        "type": "ROW_COUNT",
        "name": "Row count grouped by customer_id",
        "entityType": "table",
        "absolutePath": "METAPLANE_DB.TEST_SCHEMA.orders"
      },
      "group": [
        {
          "name": "customer_id",
          "value": "1"
        }
      ]
    }
  ]
}