Skip to content

Using webhooks in UbiOps

Webhooks enable you to listen for events in your project, so you can automatically trigger follow-up actions in the rest of your stack. For example, you can trigger an internal service when a deployment finishes a request, or you can automatically notify your team members through Slack each time a deployment or pipeline fails.

Configuring a webhook

Webhooks in UbiOps can be configured through the UbiOps WebApp, Python client library and API. Each webhook needs to be tied to a specific object in your project (deployment, pipeline, experiment). Webhooks can be found in the WebApp in the Monitoring section.

A webhook can listen to one of the following four events:

  • Request started: this event is triggered when a request to the configured object changes to status processing.
  • Request finished: this event is triggered when a request finishes, regardless of whether it finished in a failed or successful state.
  • Request completed: this event is triggered when a request completes successfully.
  • Request failed: this event is triggered when a request fails.

creating a webhook

Webhook payload

The webhook payload that is sent to the configured callback URL contains the request id, request status, information about the object that the webhook was configured for, and a textual description of the event that can for example be used for Slack integration.

If the include_result parameter is set to True and the result is smaller than 16 kB, then the result of the request is included as well.

Below you can see an example webhook payload:

{
    "event": "deployment_request_completed",
    "deployment_id": "<uuid>",
    "deployment_name": "<uuid>",
    "deployment_version_id": "<uuid>",
    "deployment_version_name": "<uuid>",
    "request_id": "<uuid>",
    "status": "completed",
    "result": "...", // Only if <= 16kb
    "text": "Deployment request <uuid> finished for deployment <name> <version> in project <project-name>"
}

Headers for the webhook request

It is possible to configure additional HTTP headers for the webhook request that is made to your callback URL.

If the header contains sensitive data, you can mark that header as a secret by passing protected: True. This way the value of that header will not be visible in the WebApp and will not be returned when using the GET endpoint to retrieve the webhook details.

Below you can find an example configuration that specifies a secret header:

{
  "name": "webhook-1",
  "url": "https://callback-url-webhook-1.com",
  "headers": [
    {
      "key": "Authorization",
      "value": "Token 123",
      "protected": true
    }
  ],
  "object_type": "pipeline",
  "object_name": "pipeline-1",
  "version": "v1",
  "event": "pipeline_request_started",
}

Testing webhooks

A test endpoint is available which enables you to test your webhook configuration with a dummy event. You can do this in the UbiOps WebApp, either when creating a Webhook or from the details page of an existing webhook. You can also test it via the API or the Python client library.

webhook test section

Using webhooks for training runs

You can also use webhooks for training runs. To enable this, simply create a webhook that is tied to the training-base-deployment and points to the version with the name of your experiment. Every run within that experiment is treated as a request and therefore the webhook can listen to the same four events.