How Do Webhooks Work in Arthur?

Arthur provides the ability to configure webhooks when Alerts are found for a model that send the information of the
Alert to your downstream incident management system. In order to support a wide range of integrations, Arthur provides a webhook templating engine, using Jinja2 syntax. This allows you to render the alert information into a webhook payload format your downstream system understands.

Creating a Webhook

To get started creating a webhook, navigate to "Workspace Settings", "Integrations/Webhooks" page in the Arthur
navigation menu.

Once there, click the "ADD WEBHOOK" button to get started creating a new webhook. First, give your webhook a name, then click "Next". Then you should see the following form to enter your webhook information.

See the What are Webhooks? page for an explanation of what each of these
fields means. For the purpose of this example, we'll use https://webhook.site as a sample webhook. This site can set up sample webhook responses, and tracks the webhooks it receives to better debug a webhook's configuration.

To get started, enter your webhook's URL in the URL field. By default, it is masked in case any tokens or secrets are
present in the URL. Next, in the header section, enter content-type for Name, and application/json for Value. Again, the headers are masked by default in case they contain passwords or tokens. Lastly, enter the following payload in the payload field:

{
  "alerts": {{ alerts | tojson }},
  "model": {{ model | tojson }}
}

To recap, this is what the complete webhook form should look like:

Clicking "TEST WEBHOOK" should then show a "Webhook succeeded with status code 200" success message, which means the webhook is ready to go!

Payload Information for Rendering

In the example above, we created a simple payload using Jinja2 syntax that showed all the data available to the
template. The template has two objects, alerts which is a list of alert objects, and model which is information about the model for which the alerts were found.

A full example of the format of the data is shown below:

{
  "alerts": [
    {
      "alert_rule_id": "1b1b1b1b-1b1b-1b1b-1b1b-1b1b1b1b1b1b",
      "alert_rule_metric_name": "test_alert_rule_metric_name_1",
      "alert_rule_name": "test_alert_rule_name_1",
      "bound": "upper_bound",
      "created_at": "2021-09-01T00:00:00+00:00",
      "description": "test alert 1",
      "dimensions": {
        "test_dimensions_key_1": "test_dimensions_val_1"
      },
      "id": "1a1a1a1a-1a1a-1a1a-1a1a-1a1a1a1a1a1a",
      "job_id": null,
      "metric_version": 1,
      "model_id": "1d1d1d1d-1d1d-1d1d-1d1d-1d1d1d1d1d1d",
      "threshold": 0.5,
      "timestamp": "2021-09-01T00:00:00+00:00",
      "updated_at": "2021-09-01T00:00:00+00:00",
      "value": 1.0
    },
    ...
  ],
  "model": {
    "created_at": "2024-10-04T14:23:20.724226+00:00",
    "dataset_id": "00000000-0000-0000-0000-000000000002",
    "description": "Test webhook model",
    "id": "00000000-0000-0000-0000-000000000000",
    "last_updated_by_user": null,
    "metric_config": {
      "aggregation_specs": [],
      "id": "00000000-0000-0000-0000-000000000003"
    },
    "name": "Test webhook model",
    "project_id": "00000000-0000-0000-0000-000000000001",
    "schedule": null,
    "updated_at": "2024-10-04T14:23:20.724230+00:00"
  }
}