Prefect Docs

# Cloud Hooks

Looking for the latest Prefect 2 release? Prefect 2 and Prefect Cloud 2 have been released for General Availability. See https://docs.prefect.io/ for details.

Psst! We have recently added Automations which offer more functionality than Cloud Hooks and will eventually replace them.

Cloud Hooks allow you to send notifications to certain endpoints when your flow enters a given state. For example, you can send a Slack message to your team when a production-critical flow has failed, along with the reason for the failure, so you can respond immediately. The Prefect backend API currently supports hooks for Slack, Twilio, Pager Duty, email, and a more general Webhook.

You can set up and edit your Cloud Hooks using the API or the Flow Settings page in the UI.

# UI

For all Cloud Hooks, you can choose a name for the hook (the default is 'Custom') and decide which states you want to be alerted about. Different inputs are required depending on the type of Cloud Hook.

 

# Email Cloud Hook

To set up an Email Cloud Hook, enter an email in the "To" section. The email you enter will receive formatted emails that contain state updates and a link to the flow for which this Cloud Hook is configured.

# Web Cloud Hook

The Web Cloud Hook operates as an all-purpose webhook and can hit any endpoint.

To set up a Web Cloud Hook, enter the URL that you want Prefect to POST a JSON payload to when your flow enters your configured states.

# Slack Cloud Hook

To set up a Slack Cloud Hook, you will need to create an incoming webhook for your slack channel. Slack's docs talk you through how to create a Slack app and create an incoming webhook (and it's even easier than that sounds!)

Once you have an incoming webhook URL, you can copy it into the 'Slack URL' section of the Slack Cloud Hook form.

# Twilio Cloud Hook

A Twilio Cloud Hook needs a few more inputs: an Auth Token, an Account SID, a Messaging Service SID and at least one phone number.

The phone number is the number that you want alerts to be sent to.

The Auth Token and Account SID are on your Twilio project dashboard.

 

The Messaging Service SID requires you to have a messaging service set up. These instructions are for the programmable SMS service.

  1. Click on the "All Products and Services" option in the side-menu.

 

  1. Select "Programmable SMS"
  2. Select SMS
  3. Click on the "Create New Messaging Service" icon

 

  1. Give your project a name and check the settings.
  2. Click on 'Numbers' and add a number to your account. (This is not the number your messages will get sent to so you don't need to enter this in the Prefect Cloud Hooks form.)
  3. Your Messaging Service SID is the Service SID in the Settings page.

# Pager Duty Cloud Hook

For a Pager Duty token, you'll need an API Token and an Integration Key. You'll also need to select a Severity level from the dropdown menu.

The API Token comes from the API Access section of the Configuration menu of the Pager Duty dashboard.

 

To find your Integration Key, you also need the Configuration menu but choose Services. Select the service you want to add a Cloud Hook to and then click on the Integrations tab.

 

In Integrations, select "New integration" and create a new integration using the API.

 

Your Integration Key will show in the integrations list.

 

# API

To create a Cloud Hook using the API, you can use the create_cloud_hook mutation. For example, to create an email Cloud Hook you'd use the following mutation:

mutation {
  create_cloud_hook(
    input: {
      type: EMAIL,
      name: "Example",
      version_group_id: "abc",
      states: ["Running"],
      config: "{\"to\": \"test@test.com\"}"}
      ) {
    id
  }
}

A full list of Cloud Hook queries and mutations can be found in the API schema (for example in the Interactive API page of the UI.)

← Services →