The new Slack platform and the features described below are in beta and under active development.

Webhook Triggers

Invoke a workflow when a specific URL receives a POST request

Webhook triggers are an automatic type of trigger that listens for a certain type of data, much like event triggers.

While event triggers are used for activating a trigger based on internal activity, webhooks are instead used when activating a trigger based on external activity. In other words, webhook triggers are useful when tying Slack functionality together with non-Slack services.

There are two steps to using a webhook trigger:

  1. Create a trigger, either via the CLI or at runtime
  2. Invoke the trigger with a POST Request

1. Create a webhook trigger

Triggers can be added to workflows in two ways:

  • You can add triggers with the CLI. These static triggers are created only once. You create them with the Slack CLI, attach them to your app's workflow, and that's that. The trigger is defined within a trigger file.

  • You can add triggers at runtime. These dynamic triggers are created at any step of a workflow so they can incorporate data acquired from other workflow steps. The trigger is defined within a function file.

Create a webhook trigger with the CLI

Slack CLI built-in documentation
Use slack trigger --help to easily access information on the trigger command's flags and subcommands.

Before you can create a trigger with the CLI, you'll need to be running your app locally in a development environment (with the slack run command) or have deployed your app in production (with the slack deploy command).

The triggers you create when running locally will not work when you deploy your app in production. You'll need to create any triggers again with the CLI.

Create the trigger file

To create a webhook trigger with the CLI, you'll need to create a trigger file. The trigger file contains the payload you used to define your trigger.

Create a TypeScript trigger file within your app's folder with the following form:

import { Trigger} from “deno-slack-api/types.ts”;

const trigger : Trigger<typeof ExampleWorkflow.definition> = {
  // your TypeScript payload 
}

export default trigger;

Your TypeScript payload consists of the parameters needed for your own use case. The following is a TypeScript payload for creating a webhook trigger:

  type: "webhook",
  name: "sends 'how cool is that' to my fav channel",
  description: "runs the example workflow",
  workflow: "#/workflows/myWorkflow",
  inputs: {
    stringToReverse: {
      value: "how cool is that",
    },
    channel: {
      value: "{{data.channel}}",
    },
  }

Once you have created a trigger file, use the following command to create the webhook trigger:

slack trigger create --trigger-def "path/to/trigger.ts"

Create a webhook trigger at runtime

The logic of a runtime trigger lies within a function's TypeScript code. Within your functions folder, you'll have the functions that are the steps making up your workflow. Within this folder is where you can create a trigger within the relevant <function>.ts file.

When you create a runtime trigger, you can leverage inputs acquired from functions within the workflow. Provide the workflow definition to get additional typing for the workflow and inputs fields.

Create a webhook trigger at runtime using the client.workflows.triggers.create method within the relevant function file.

const triggerResponse = await client.workflows.triggers.create<typeof ExampleWorkflow.definition>({
  // your TypeScript payload
);

Your TypeScript payload consists of the parameters needed for your own use case. Below is a function file with an example TypeScript payload for a webhook trigger.

// functions/example_function.ts
import { DefineFunction, Schema, SlackFunction } from "deno-slack-sdk/mod.ts";
import { SlackAPI } from "deno-slack-api/mod.ts"; 

export const ExampleFunctionDefinition = DefineFunction({
  callback_id: "example_function_def",
  title: "Example function",
  source_file: "functions/example_function.ts",
});

export default SlackFunction(
  ExampleFunctionDefinition,
  ({ inputs, client }) => {

  
  const triggerResponse = await client.workflows.triggers.create<typeof ExampleWorkflow.definition>({
    type: "webhook",
    name: "sends 'how cool is that' to my fav channel",
    description: "runs the example workflow",
    workflow: "#/workflows/myWorkflow",
    inputs: {
      stringToReverse: {
        value: "how cool is that",
      },
      channel: {
        value: "{{data.channel}}",
      },
    }
  });

  // ...

Parameters

Field Description Required
type The type of trigger: webhook Required
name The name of the trigger Required
workflow Path to workflow that the trigger initiates Required
description The description of the trigger
inputs The inputs provided to the workflow
webhook Contains filter, if desired
webhook.filter See trigger Filters

Webhook trigger response

The response will have a property called ok. If true, then the trigger was created, and the trigger property will be populated.

Your response will include a trigger.id; be sure to store it! You use that to update or delete the trigger if need be. Perhaps consider storing it in a datastore.

2. Invoke the trigger

Send a POST request to invoke the trigger. Within that POST request you can send values for specific inputs.

Example POST request

curl \ 
-X POST "https://hooks.slack.com/triggers/T123ABC456/.../..." \
--header "Content-Type: application/json" \
--data "{"channel":"C123ABC456"}" 

If successful, you'll get the following response:

{
  "ok":true
}

Manage a webhook trigger

A newly created Trigger will only be accessible to others inside a workspace once its creator has granted access using the access Slack CLI command.

Grant access

Required Flag Description Example Argument
--trigger-id Provide the trigger_id as the argument Ft123ABC
--grant A switch to grant access

Set one of the following flags to grant access to different groups of people.

Flag Description Example Argument
--users Provide the user_id of desired users as the argument U123ABC U456DEF
--app-collaborators A switch to control access of all app collaborators
--everyone A switch to control access of all workspace members

The following example command grants access to the Trigger FtABC123 for users U123ABC and U456DEF.

slack trigger access --trigger-id FtABC123 --users U123ABC U456DEF --grant

Revoke access

Flag Description Example Argument
--trigger-id Provide the trigger_id as the argument Ft123ABC
--users Provide the user_id of desired users as the argument U123ABC U456DEF
--revoke A switch to revoke access

The following example command revokes access to the Trigger FtABC123 for users U123ABC and U456DEF.

slack trigger access --trigger-id FtABC123 --users U123ABC U456DEF --revoke

Update a webhook trigger

Update a Trigger with the CLI

Make an update to a pre-existing Trigger with the CLI by using the slack trigger update command. Provide the same payload you used to create the trigger in its entirety, in addition to the Trigger ID.

slack trigger update --trigger-id Ft123ABC --trigger-def "path/to/trigger.ts"

Update a Trigger at runtime

You can update a runtime Trigger, but the Trigger must be updated in its entirety. Use the same structure as client.workflows.triggers.create() but for client.workflows.triggers.update with the additional trigger_id parameter.

client.workflows.triggers.update<typeof ExampleWorkflow.definition>({
  trigger_id: "FtABC123",
  type: "<specific-trigger-type>",
  name: "My Trigger",
  workflow: "#/workflows/myworkflow",
  inputs: {
    input_name: {
      value: "value",
    }
  }
});

Delete a webhook trigger

Delete a Trigger with the CLI

You can delete a Trigger with the slack trigger delete command.

slack trigger delete --trigger-id FtABC123

Delete a Trigger at runtime

Deleting a runtime Trigger deletes that specific Trigger created in one instance of the Workflow. This means that you'll need to have stored the trigger_id created for that instance. Your app will continue to be able to create Triggers until you remove the relevant code.

You can delete a runtime Trigger by using client.workflows.triggers.delete().

client.workflows.triggers.delete({
   trigger_id: "FtABC123"
});