# Webhooks

Webhooks allow external services to trigger workflow execution by sending HTTP requests to your workflow. SteelEngine supports two approaches for webhook-based triggers.

## Generic Webhook Trigger

The Webhook block (the Generic Webhook trigger) creates a flexible endpoint that can receive any payload and trigger your workflow:

![Generic Webhook Configuration](https://docs.steelengine.com/static/blocks/webhook-trigger.png)

### How It Works

1. **Add Webhook Block** - Drag the Webhook block from the toolbar's Triggers section to start your workflow
2. **Configure Payload** - Set up the expected payload structure in Input Format (optional)
3. **Get Webhook URL** - Copy the generated endpoint, `https://steelengine.com/api/webhooks/trigger/<path>`, where `<path>` is unique to this trigger
4. **External Integration** - Configure your external service to send POST requests to this URL
5. **Workflow Execution** - Every request to the webhook URL triggers the deployed workflow

The triggered run uses the workflow's [Execution timeout](/execution#workflow-timeouts), if configured, including waits and approval pauses. Otherwise, platform async defaults apply. This runtime limit is separate from the HTTP acknowledgement sent to the webhook caller.

### Features

* **Flexible Payload**: Accepts any JSON payload structure
* **Automatic Parsing**: The JSON body is parsed and its fields are available to subsequent blocks as `<webhook1.fieldName>`
* **Authentication**: Bearer token or custom header authentication, on by default with a generated token
* **Rate Limiting**: Built-in protection against abuse
* **Deduplication**: Skips repeated deliveries when the request carries a recognized delivery id or you set a Deduplication Field (see below)

The Generic Webhook trigger fires every time the webhook URL receives a request, making it perfect for real-time integrations.

### Block Options

* **Require Authentication**: On by default. Every request must then carry the **Authentication Token**. SteelEngine generates the token when you add the block. Set **Secret Header Name** to send the token in a custom header, for example `X-Secret-Key`, instead of `Authorization: Bearer TOKEN`.
* **Deduplication Field**: A dot-notation path to a unique value in the payload, such as `event.id`. When the same value arrives again within 7 days, SteelEngine skips the duplicate. Without it, SteelEngine deduplicates only on standard delivery-id headers such as `webhook-id`, `x-github-delivery`, `svix-id`, `idempotency-key`, or `x-steelengine-idempotency-key`. Requests with none of these run every time.
* **Acknowledgement**: **Default** answers accepted requests with `200` and `{"message":"Webhook processed"}`. **Custom** answers with an empty `200` response.
* **Input Format**: Optional schema for the expected JSON body. Use type `file[]` for fields that carry uploaded files.

## Trigger Mode for Service Blocks

Alternatively, you can use specific service blocks (like Slack, GitHub, etc.) in "trigger mode" to create more specialized webhook endpoints:

[Video: slack-trigger.mp4](https://d4h6f8f5tksdw.cloudfront.net/slack-trigger.mp4)

### Setting Up Trigger Mode

1. **Add Service Block** - Open the toolbar's **Triggers** section. Drag or click the service you want, such as Slack, GitHub, or Airtable. This adds the block in trigger mode. The same service added from the **Blocks** section is an action block
2. **Pick the Event** - Choose the event the trigger should listen for
3. **Configure Service** - Set up authentication and event filters specific to that service
4. **Webhook Registration** - Follow the provider's setup instructions. Some services register a webhook automatically; Slack uses the Events API URL configured on the installed app
5. **Event-Based Execution** - Workflow triggers only for specific events from that service

Slack triggers select a bot installation and filter its subscribed event stream. Multiple workflows can use the same app URL. Configure subscriptions on the app, then choose event and channel filters on each trigger. See [Slack Events and Channels](/credentials/custom-apps#events-and-channels).

### When to Use Each Approach

**Use Generic Webhook when:**

* Integrating with custom applications or services
* You need maximum flexibility in payload structure
* Working with services that don't have dedicated blocks
* Building internal integrations

**Use Trigger Mode when:**

* Working with supported services (Slack, GitHub, etc.)
* You want service-specific event filtering
* You need automatic webhook registration
* You want structured data handling for that service

## Supported Services for Trigger Mode

Every integration in the toolbar's Triggers section supports trigger mode. The [Integration Triggers](/triggers#integration-triggers) list on the Triggers overview shows each provider, its number of events, and a link to its tool page.

Email and Google Workspace triggers (Gmail, Outlook, IMAP Email, Google Calendar, Google Drive, Google Sheets) poll the account on a schedule instead of receiving webhooks. They need no webhook registration. SteelEngine disables them after 100 consecutive failed polls.

## Security and Best Practices

### Authentication Options

* **Bearer Tokens**: Include `Authorization: Bearer <token>` header
* **Custom Headers**: Define custom authentication headers

### Payload Handling

* **Validation**: Validate incoming payloads to prevent malformed data
* **Body Format**: SteelEngine parses JSON bodies as JSON. It parses `application/x-www-form-urlencoded` bodies into an object. If a form body carries a `payload` field, SteelEngine parses that field as JSON instead
* **Deduplication**: Set a Deduplication Field so retried deliveries do not run the workflow twice

### Testing Webhooks

1. Use tools like Postman or curl to test your webhook endpoints
2. Check workflow execution logs for debugging
3. Verify payload structure matches your expectations
4. Test authentication and error scenarios

Always validate and sanitize incoming webhook data before processing it in your workflows.

## Common Use Cases

### Real-time Notifications

* Slack messages triggering automated responses
* Email notifications for critical events

### CI/CD Integration

* GitHub pushes triggering deployment workflows
* Build status updates
* Automated testing pipelines

### Data Synchronization

* Airtable changes updating other systems
* Form submissions triggering follow-up actions
* E-commerce order processing

### Customer Support

* Support ticket creation workflows
* Automated escalation processes
* Multi-channel communication routing

## Common Questions

**What HTTP methods does the Generic Webhook endpoint accept?**

The webhook endpoint handles POST requests for triggering workflows. GET requests are only used for provider-specific verification challenges (such as Microsoft Graph or WhatsApp verification). Other methods return a 405 Method Not Allowed response.

**How do I authenticate webhook requests?**

Require Authentication is on by default and the block generates an Authentication Token when you add it. Callers send the token as a Bearer token in the Authorization header, or you can specify a custom header name (e.g., X-Secret-Key) and the token will be matched against that header instead. Requests with a missing or wrong token receive 401.

**Can I define the expected payload structure for a webhook?**

Yes. The Webhook block includes an Input Format field where you can define the expected JSON schema. This is optional but helps document the expected structure. You can also use type "file[]" for file upload fields.

**Does the webhook have deduplication built in?**

Only when the request carries a stable delivery identifier. SteelEngine reads standard delivery-id headers (webhook-id, x-github-delivery, svix-id, idempotency-key, x-steelengine-idempotency-key, and similar) or the payload path you set in Deduplication Field. It skips a repeat of the same identifier within 7 days. A request with neither runs the workflow again, even if the payload is identical.

**What data from the webhook request is available in my workflow?**

The parsed request body is the trigger's output. Reference its fields with dot notation, for example <webhook1.message> or <webhook1.data.key>. Request headers and query parameters are not passed to the workflow.

**Do I need to deploy my workflow for the webhook URL to work?**

Yes. The webhook endpoint checks that the associated workflow is deployed before triggering execution. If the workflow is not deployed, the webhook returns 403. If the workflow is deployed but this trigger was saved after that deployment, it returns 409 with the message "Webhook must be redeployed before it can execute". An unknown webhook path returns 404.

**Does the webhook auto-disable after repeated failures?**

No. Unlike polling-based triggers (RSS, Gmail, IMAP), push-based generic webhooks do not auto-disable after consecutive failures. Each incoming request is processed independently. If your workflow consistently fails, check the execution logs for error details.
