# Buzz Workflow Action Types: A Complete Guide to Automation Steps

> Explore Buzz workflow action types like SendMessage, CallWebhook, and RequestApproval to automate tasks and streamline your development process within the block/buzz repository.

- Repository: [Block Open Source/buzz](https://github.com/block/buzz)
- Tags: how-to-guide
- Published: 2026-08-27

---

**Buzz provides seven distinct workflow action types—SendMessage, SendDm, SetChannelTopic, AddReaction, CallWebhook, RequestApproval, and Delay—that enable automated messaging, channel management, external integrations, and human-in-the-loop approvals within the block/buzz repository.**

The block/buzz repository implements a powerful workflow engine in the `buzz-workflow` crate, where automation logic is defined through an ordered sequence of steps. Each step contains an **action type** specified by the `ActionDef` enum, which determines exactly what operation the executor performs when the workflow runs. Understanding these action types is essential for building effective automations that respond to triggers ranging from message reactions to scheduled cron jobs.

## Understanding the ActionDef Enum

The core definition of all workflow action types resides in [`crates/buzz-workflow/src/schema.rs`](https://github.com/block/buzz/blob/main/crates/buzz-workflow/src/schema.rs), specifically within the `ActionDef` enum. This enum uses **internally tagged serialization** with `#[serde(flatten)]` to allow each workflow step to specify exactly one action type alongside its configuration parameters.

When the workflow engine parses a YAML definition, it flattens the action-specific fields directly into the step object. This design means a step's configuration contains both universal metadata (like `id`) and action-specific fields (like `text` or `url`) at the same object level, making the configuration intuitive while maintaining strict type safety in the Rust implementation.

## Available Workflow Action Types in Buzz

The `ActionDef` enum in [`crates/buzz-workflow/src/schema.rs`](https://github.com/block/buzz/blob/main/crates/buzz-workflow/src/schema.rs) currently supports seven distinct action types, each designed for specific automation scenarios.

### SendMessage

The `SendMessage` action posts a message to a channel, supporting both new conversations and threaded replies. This is the most commonly used action type for notifications and automated responses.

Key configuration fields include:
- `text` – The message body supporting template variables (e.g., `{{trigger.author}}`)
- `channel` – Optional UUID specifying a target channel different from the workflow's default
- `reply_in_thread` – Boolean flag that, when `true`, forces the bot to reply to the triggering message rather than starting a new thread

According to the validation logic in `WorkflowDef::validate`, this action type cannot use `reply_in_thread: true` when the workflow trigger lacks message context, such as schedule-based or generic webhook triggers.

### SendDm

The `SendDm` action delivers direct messages to specific users, enabling private notifications that avoid channel noise. This action type requires:
- `to` – The recipient's public key or a template expression like `{{trigger.author}}`
- `text` – The private message content

This action is particularly useful for sending sensitive alerts or personal task assignments that should not appear in public channels.

### SetChannelTopic

The `SetChannelTopic` action updates the topic line of the workflow's associated channel. It accepts a single required field:
- `topic` – The new topic string to display

This action type helps teams automate channel context updates, such as rotating on-call engineer names or displaying current sprint information.

### AddReaction

The `AddReaction` action adds emoji reactions to messages programmatically, providing lightweight acknowledgment mechanisms. The configuration requires:
- `emoji` – The emoji name (e.g., `"thumbsup"` or `"white_check_mark"`)

This action only functions correctly when triggered by message-oriented events that provide a target message ID for the reaction attachment.

### CallWebhook

The `CallWebhook` action enables external integrations by executing HTTP requests to third-party endpoints. This action type supports sophisticated API interactions with the following fields:
- `url` – The target HTTPS endpoint (required)
- `method` – Optional HTTP verb (defaults to `POST`)
- `headers` – Optional map of additional HTTP headers
- `body` – Optional request payload supporting template variable interpolation

Security validation in `WorkflowDef::validate` restricts this action type to workflows owned by users with elevated channel authority, preventing unauthorized external data exfiltration.

### RequestApproval

The `RequestApproval` action implements human-in-the-loop workflows by pausing execution until explicit authorization is granted. This action creates approval gates with these parameters:
- `from` – User mention or role identifier (e.g., `"@release-manager"`)
- `message` – Descriptive text presented to the approver
- `timeout` – Optional duration string (defaults to `"24h"`)

If the approval is denied or the timeout expires, the workflow execution stops, making this action critical for deployment pipelines and sensitive operations requiring oversight.

### Delay

The `Delay` action inserts timed pauses between workflow steps, useful for rate limiting or waiting for external processes to complete. It requires:
- `duration` – Human-readable time period (e.g., `"5m"`, `"1h"`, `"30s"`)

The executor parses these duration strings and suspends workflow processing for the specified interval before resuming with the next step.

## How Actions Are Defined in YAML

Buzz workflows use **flattened serialization** to keep configuration files readable. Each step includes an `action` field that acts as the discriminant for the `ActionDef` enum, with the remaining fields depending on the selected action type.

```yaml
- id: notify
  action: send_message
  text: "Build succeeded"
  channel: "general"
  reply_in_thread: true

```

This structure maps directly to the Rust enum definition in [`crates/buzz-workflow/src/schema.rs`](https://github.com/block/buzz/blob/main/crates/buzz-workflow/src/schema.rs), where `#[serde(flatten)]` combines the action tag with its specific payload fields into a cohesive step definition.

## Workflow Validation and Security Constraints

Before persisting workflow definitions, the system performs rigorous validation through `WorkflowDef::validate`. This validation enforces critical constraints on how workflow action types can be used:

- **Context Validation**: Actions like `SendMessage` with `reply_in_thread: true` are rejected if the trigger type (such as `schedule` or generic `webhook`) does not provide a message context object.
- **Permission Verification**: The `CallWebhook` action requires the workflow owner to possess elevated channel authority, ensuring only trusted users can configure external HTTP requests.
- **Enum Integrity**: All action tags must correspond to valid `ActionDef` variants defined in the schema.

These safety checks prevent runtime failures and security vulnerabilities by catching configuration errors during the save operation rather than during execution.

## Summary

- The `ActionDef` enum in [`crates/buzz-workflow/src/schema.rs`](https://github.com/block/buzz/blob/main/crates/buzz-workflow/src/schema.rs) defines seven workflow action types: **SendMessage**, **SendDm**, **SetChannelTopic**, **AddReaction**, **CallWebhook**, **RequestApproval**, and **Delay**.
- Each action type serves specific automation needs, from public channel messaging to private approvals and external HTTP integrations.
- Workflow definitions use flattened YAML syntax where the `action` field selects the enum variant and remaining fields configure the specific behavior.
- The validation system enforces security constraints, such as requiring elevated permissions for webhooks and verifying message context for thread replies.
- Type definitions are mirrored in TypeScript at [`desktop/src/shared/api/workflowTypes.ts`](https://github.com/block/buzz/blob/main/desktop/src/shared/api/workflowTypes.ts) to maintain consistency between the Rust backend and desktop client interface.

## Frequently Asked Questions

### How do I configure the SendMessage action type to reply in a thread?

Set the `reply_in_thread` field to `true` in your workflow step configuration. Note that this only works when the workflow trigger provides message context, such as a reaction trigger or message trigger. If you attempt to use this with a cron schedule trigger or generic webhook, the `WorkflowDef::validate` method will reject the configuration because no parent message exists to thread under.

### What permissions are required to use the CallWebhook action in Buzz workflows?

The `CallWebhook` action type requires the workflow owner to have elevated channel authority, as enforced by the validation logic in [`crates/buzz-workflow/src/schema.rs`](https://github.com/block/buzz/blob/main/crates/buzz-workflow/src/schema.rs). This security measure prevents standard users from configuring workflows that could transmit channel data to external URLs. Only users with appropriate administrative privileges can save workflows containing webhook actions.

### Can I combine multiple workflow action types in a single Buzz workflow?

Yes, Buzz workflows support sequential combinations of different action types within the `steps` array. For example, you can chain an `AddReaction` action to acknowledge a trigger, followed by a `Delay` action for rate limiting, and conclude with a `SendMessage` action containing the final results. The executor processes each step in order, with actions like `RequestApproval` pausing execution until the human approval condition is met.

### Where is the workflow action execution logic implemented in the block/buzz codebase?

While the action definitions and schema validation reside in [`crates/buzz-workflow/src/schema.rs`](https://github.com/block/buzz/blob/main/crates/buzz-workflow/src/schema.rs), the actual execution logic for these workflow action types is implemented in [`crates/buzz-workflow/src/executor.rs`](https://github.com/block/buzz/blob/main/crates/buzz-workflow/src/executor.rs). This executor file handles the runtime behavior of each action, such as making HTTP requests for `CallWebhook` or invoking the messaging APIs for `SendMessage`. The relay API endpoint at [`crates/buzz-relay/src/api/workflows.rs`](https://github.com/block/buzz/blob/main/crates/buzz-relay/src/api/workflows.rs) handles the CRUD operations for workflow definitions, while the desktop interface uses components in [`desktop/src/features/workflows/ui/workflowFormPrimitives.tsx`](https://github.com/block/buzz/blob/main/desktop/src/features/workflows/ui/workflowFormPrimitives.tsx) to render action type selectors.