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

Schema

You can expect the payload to match this schema:

{
    id: string;
    labels: Array<{
        name: string;
        id: string;
    }>;
    status: "opened" | "resolved";
    updatedAt: string;
    createdAt: string;
    idempotencyId: string;
    acknowledged: boolean;
    acknowledgedAt: string | null;
    incidentUrl: string;
    affectedMonitors_v2: Array<{
        id: string;
        monitor: Array<{
            name: string | null;
            type: string;
            id: string;
            tags: Array<{
                name: string;
            }>;
            entities: Array<{
                id: string;
                connectionId: string;
                entityType: string;
                absolutePath: string;
            }>;
            owners: Array<{
                name: string;
                email: string;
                identities: Array<
                | {
                    type: "slack";
                    userId: string;
                }
                | {
                    type: "ms_teams";
                    userId: string;
                }
                | {
                    type: "dbt";
                    ownerId: string;
                }
                >;
            }>;
        }>;
        group: Array<{
            name: string;
            value: string;
        }> | null;
        linkedAt: string;
        resolvedAt: string | null;
        connections: Array<{
            name: string | null;
            type: string;
            id: string;
        }>;
    }>;
    /* affectedMonitors is deprecated. Please use affectedMonitors_v2 */
    affectedMonitors: Array<{
        id: string;
        monitor: {
            name: string | null;
            type: string;
            id: string;
            tags: Array<{
                name: string;
            }>;
            entityType: string;
            absolutePath: string;
            owners: Array<{
                name: string;
                email: string;
                identities: Array<
                | {
                    type: "slack";
                    userId: string;
                }
                | {
                    type: "ms_teams";
                    userId: string;
                }
                | {
                    type: "dbt";
                    ownerId: string;
                }
                >;
            }>;
        };
        group: Array<{
            name: string;
            value: string;
        }> | null;
        linkedAt: string;
        resolvedAt: string | null;
        connections: Array<{
            name: string | null;
            type: string;
            id: string;
        }>;
    }>;
};

Delivery semantics

The webhook systems conforms to at-least-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`

affectedMonitors is now deprecated. Please use affectedMonitors_V2

The items within affectedMonitors_V2 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.

`acknowledged` and `acknowledgedAt`

As of September 16th, 2024 the acknowledged and acknowledgedAt fields are deprecated. While the payload fields will continue to exist for backward compatibility, there is no longer a way to affect the acknowledged state of an incident.

Instead, the labels field has superseded acknowledge functionality.

Example

{
  "id": "25674",
  "createdAt": "2024-03-18T14:10:56.757Z",
  "updatedAt": "2024-09-30T18:22:07.603Z",
  "idempotencyId": "MjU2NzQtMjAyNC0wOS0zMFQxODoyMjowNy42MDNa",
  "status": "opened",
  "acknowledged": false,
  "acknowledgedAt": null,
  "incidentUrl": "https://app.metaplane.dev/incident/25674",
  "affectedMonitors_v2": [
    {
      "id": "26084",
      "linkedAt": "2024-03-18T14:11:08.300Z",
      "resolvedAt": null,
      "monitor": {
        "id": "018e51e4-8ed9-7bc3-9aee-3d6011375577",
        "type": "CUSTOM",
        "name": "Group Monitor",
        "entities": [
          {
            "id": "1803f576-2b43-4f4b-b7a5-8d66a898d063",
            "connectionId": "a903aa1f-67d2-46c4-8a69-4553d3709151",
            "entityType": "database",
            "absolutePath": "DEMO_DB"
          }
        ],
        "owners": [
          {
            "name": "John Smith",
            "email": "[email protected]",
            "identities": [{ "type": "slack", "userId": "U07126QAF4X" }]
          }
        ],
        "tags": [{ "name": "dbt seed" }]
      },
      "group": [
        { "name": "group_id", "value": "7c70f325-80e2-4cda-8e06-104dc0a78270" }
      ],
      "connections": [
        {
          "id": "a903aa1f-67d2-46c4-8a69-4553d3709151",
          "type": "snowflake",
          "name": "Snowflake DB"
        }
      ]
    }
  ],
  "affectedMonitors": [
    {
      "id": "26084",
      "linkedAt": "2024-03-18T14:11:08.300Z",
      "resolvedAt": null,
      "monitor": {
        "id": "018e51e4-8ed9-7bc3-9aee-3d6011375577",
        "type": "CUSTOM",
        "name": "Group Monitor",
        "entityType": "database",
        "absolutePath": "DEMO_DB",
        "owners": [
          {
            "name": "John Smith",
            "email": "[email protected]",
            "identities": [{ "type": "slack", "userId": "U07126QAF4X" }]
          }
        ],
        "tags": [{ "name": "dbt seed" }]
      },
      "group": [
        { "name": "group_id", "value": "7c70f325-80e2-4cda-8e06-104dc0a78270" }
      ],
      "connections": [
        {
          "id": "a903aa1f-67d2-46c4-8a69-4553d3709151",
          "type": "snowflake",
          "name": "Snowflake DB"
        }
      ]
    }
  ],
  "labels": []
}