# Webhook (/workflows/triggers/webhook)





The **Webhook trigger** starts a run from an accepted request to its generated URL. Use it when an external service or application has no suitable [integration trigger](/integrations). This is inbound; the [Webhook block](/workflows/blocks/webhook) sends outbound requests.

<BlockPreview type="webhook_trigger" />

## How it works [#how-it-works]

1. Add the Webhook trigger and connect the blocks that should receive its payload.
2. Configure authentication and optional input fields.
3. Deploy the workflow, then copy **Webhook URL**.
4. Send a request and verify its run in [Logs](/logs-debugging).

Normal deliveries require the deployed trigger. The URL does not execute an undeployed workflow; provider or explicitly enabled setup-verification responses are separate from execution.

## Configuration [#configuration]

### Input format [#input-format]

Optionally define expected body fields in **Input Format** to document their shape. Use `file[]` for supported file inputs. Generic payload fields are passed through by name; the definition does not replace the need for downstream validation.

### Authentication [#authentication]

**Require Authentication** defaults on for new triggers, with a generated **Authentication Token**. Leave &#x2A;*Secret Header Name (Optional)** blank to require:

```http
Authorization: Bearer YOUR_WEBHOOK_TOKEN
```

If you set a custom secret header, send the token in that header instead. Only the configured authentication method is accepted; setting a custom header does not also permit Bearer authentication.

<Callout type="warn">
  Keep authentication enabled for workflows that access private data or perform actions. A plain browser link cannot supply the required token header. Validate payload fields before using them to select resources or perform side effects.
</Callout>

### HTTP methods and request headers [#http-methods-and-request-headers]

POST starts runs by default. Enable **Accept Other HTTP Methods** to accept GET, PUT, PATCH, and DELETE as deliveries too. Unsupported methods return `405`; provider-specific GET verification challenges are separate.

**Expose Request Headers** defaults off. When enabled, it adds a filtered `headers` object. Authorization, cookies, known credential headers, the configured secret header, and matching token values are withheld.

### Deduplication [#deduplication]

Send a stable `Idempotency-Key` for each event, or set &#x2A;*Deduplication Field (Optional)** to a scalar payload path such as `event.id`. Reuse that value for retries of the same event. Duplicate delivery identifiers are skipped within the deduplication window, currently seven days.

Without an identifier, repeated identical payloads can start separate runs. A field containing an object is not a scalar delivery identifier.

### Acknowledgement [#response]

**Acknowledgement → Default** returns a receipt after the run is queued. **Custom** lets you set **Response Status Code** and **Response Body**; a JSON body returns JSON, while other text returns plain text.

This acknowledges delivery, not workflow completion. A downstream Response block does not change the acknowledgement. Use [workflow API execution](/workflows/deployment/api) when a caller needs the completed workflow result.

Enable **Verify Test Events** only when the sender needs a setup-time validation response. It does not make an undeployed workflow runnable.

## Outputs [#outputs]

These examples use a trigger named Webhook:

| Reference | Value |
| - | - |
| `<webhook.userId>` | `userId` from the body, when present |
| `<webhook.data>` | The body's `data` field, when present |
| `<webhook.query.id>` | URL query parameter, when supplied |
| `<webhook.method>` | HTTP method, when accepting other methods is enabled |
| `<webhook.headers.x-event-name>` | Filtered request header, when header exposure is enabled |

Body fields take precedence when they already contain `query`, `method`, or `headers`. Metadata is merged only into object bodies. The generic trigger does not manufacture `event`, `id`, or `data` if the sender omitted them.

## Test it [#test-it]

This example uses the default Bearer authentication and a stable event identifier:

```bash
curl -X POST 'YOUR_WEBHOOK_URL' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $WEBHOOK_TOKEN" \
  -H 'Idempotency-Key: webhook-test-4821' \
  -d '{"event":"test","userId":"123"}'
```

Confirm `<webhook.userId>` in the run output. Send the request again with the same identifier to check deduplication, and omit the token to check authentication rejection. Use a new identifier for a new test event.

## Behavior [#behavior]

Accepted deliveries are rate-limited and can be deduplicated or refused before execution. Receipt does not guarantee the downstream run succeeds; inspect its log.

Push webhooks do not auto-disable after failed runs. Polling triggers such as RSS have separate failure counters and disabling behavior.

## Service triggers [#service-triggers]

For a service-specific trigger, enable **Use as Trigger** on a supported integration block and follow that integration's setup. Provider registration, verification, event filtering, and authentication vary by service. See [integrations](/integrations) for the supported trigger configuration.

## Related docs [#related-docs]

* [API deployment](/workflows/deployment/api)
* [Outbound Webhook block](/workflows/blocks/webhook)
* [Start](/workflows/triggers/start)