Webhooks

This page shows how to integrate NannyML to external applications by using webhooks.

Introduction

Webhook integration in NannyML Cloud enables real-time communication with external systems. When specific events occur in NannyML Cloud, it triggers webhooks—simple HTTP requests sent to URLs you define. This setup is key for automating tasks, syncing data, or triggering actions in other applications seamlessly.

To integrate webhooks, you'll set up the target URLs for these requests and, if needed, configure additional request headers, e.g. for authentication to access a secured endpoint.

Prerequisites

• You have a server application that can handle HTTP POST requests with a JSON body of a specific format, hence named the webhook server.

• The webhook server can be reached over a (private) network by your NannyML Cloud instance.

• Basic auth credentials or an authentication token in case the webhook server endpoint is secured.

Configuration

Custom webhooks configuration.

1. In the Webhook section of the application setup wizard, select the Custom webhook option.

2. In the custom webhook configuration screen, provide values for the following settings:

   1. Address: this is the full path to the webhook server endpoint that will handle the POST request sent by NannyML Cloud.

   2. Additional headers: in case additional headers are required for routing, authentication, or any other purpose, their keys and values can be configured here. After providing a key-value pair in the designated input fields, click the "plus" button to add them to the configuration. Not clicking the "plus" button will result in these values getting lost when you progress the wizard. Any added key-value pair can be removed by using the "minus" button.

Custom webhook configuration values.

3. Use the Validate webhook button to send a test request using the provided configuration. If the webhook server returns an HTTP status code of 200, the webhook is considered valid. After validation, the Next button is enabled, and you can progress to the next section of the wizard. If any other HTTP status code is returned, the webhook is considered invalid. The error message returned will be shown on the screen. To aid with debugging, we've included the validation request on the page. You will not be able to progress to the next section of the wizard when webhooks are enabled, but the configuration cannot be validated.

A validated custom webhook configuration.

Triggers and payloads

In NannyML Cloud a webhook is considered to be a notification channel. A notification will be sent, using the configured channels, when certain events occur in NannyML Cloud. Each notification sent is of a certain notification type, associated with the triggering event. Notifications will differ based on the channel they are sent over (e.g. email, webhook, ...) and the notification type. For webhooks each notification type is associated with a certain payload. This is essentially a JSON representation of data relevant to the trigger event.

RunCompleted

Trigger

This notification triggers whenever a run is completed. This includes runs that fail.

Payload example

{
  "header": {
    "model_name": "test",
    "model_id": 28740,
    "notification_type": "RUN_COMPLETED"
  },
  "payload": {
    "run": {
      "started_at": "2024-01-25T14:04:10.157236"
    },
    "performance_alerts": {
      "cbpe": [
        {
          "metric_name": "specificity"
        }
      ]
    },
    "other_alerts": {
      "univariate_drift": [
        {
          "metric_name": "country"
        }
      ]
    },
    "success": [
      "unseen_values",
      "missing_values"
    ],
    "report_link": "https://test.app.nannyml.com/model/1"
  }
}