# Webhook

Start a workflow when its own web address is called.

## Start a workflow

Add a trigger and choose **Webhook**.

### Catch Webhook

Triggers when an HTTP request is received. Supports GET, POST, PUT, PATCH, DELETE and any other HTTP method.

- **Authentication · Optional**: How callers prove they are allowed to trigger this webhook. Pick None to accept any request. Any other value refuses every request, and the secrets below are compared exactly as written ({{ }} is not filled in here). Options: None, Basic Auth, Header Auth, HMAC Signature. Default: None.
- **Username · Required**: The username expected in the Basic Auth header. Shows when **Authentication** is **Basic Auth**.
- **Password · Required**: The password expected in the Basic Auth header. Shows when **Authentication** is **Basic Auth**.
- **Header Name · Required**: The name of the header to check (such as X-Api-Key). Shows when **Authentication** is **Header Auth**.
- **Signature Header · Required**: The header carrying the signature (such as X-Hub-Signature-256, X-Signature). Shows when **Authentication** is **HMAC Signature**.
- **Header Value · Required**: The expected value of the authentication header. Shows when **Authentication** is **Header Auth**.
- **Shared Secret · Required**: The secret the sender signs the raw request body with. Shows when **Authentication** is **HMAC Signature**.
- **Algorithm · Optional**: The scrambling method the sender uses to sign the request. Match what their docs specify (such as SHA-256). Options: SHA-256, SHA-1, SHA-512. Default: SHA-256. Shows when **Authentication** is **HMAC Signature**.
- **Signature Encoding · Optional**: The text format the signature arrives in. Match what the sender's docs say (such as Hexadecimal). Options: Hexadecimal, Base64. Default: Hexadecimal. Shows when **Authentication** is **HMAC Signature**.
- **Signature Prefix · Optional**: Optional prefix to strip from the header value before comparing (such as "sha256="). Shows when **Authentication** is **HMAC Signature**.
- **Allowed Methods · Optional**: Restrict which HTTP methods may trigger this webhook. Leave empty to allow all. Options: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.

A later step can use its data, such as `{{trigger.body}}`, `{{trigger.headers}}`, `{{trigger.method}}` and 1 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

For a step-by-step guide, see [Start from a webhook](https://docs.gorunner.io/build/start-from-a-webhook).

## Do things in Webhook

Add a **Webhook** step. Choose the row to see all its fields.

- [Return Response](https://docs.gorunner.io/apps/webhook#fields-f-return-response): Return a custom HTTP response to the webhook caller and stop (or continue) the workflow.

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Webhook is `pieceId: "webhook"` with `actionId: "return_response"`. Its trigger is `webhook` / `catch_webhook`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It computes from its inputs only (`pure`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Webhook › Return Response

Return a custom HTTP response to the webhook caller and stop (or continue) the workflow.

- **Response Type · Optional**: Choose what to send back: structured data (JSON), plain text, or send the caller to another web address. Options: JSON, Raw Text, Redirect. Default: JSON.
- **After responding · Optional**: Stop the workflow once the response is sent, or keep running the remaining steps. Options: Stop the workflow, Keep running. Default: Stop the workflow.
- **Status Code · Optional**: The result code sent to the caller: 200 means success, 404 not found, 500 error (such as 200). Default: 200. Shows when **Response Type** isn’t **Redirect**.
- **JSON Body · Optional**: The structured data to send back to the caller, written as JSON (such as {"status": "ok"}). Shows when **Response Type** is **JSON**.
- **Raw Body · Optional**: The plain text to send back to the caller exactly as typed (such as Thanks, we got your request). Shows when **Response Type** is **Raw Text**.
- **Redirect URL · Optional**: The web address to send the caller to (such as https://example.com/thank-you). Shows when **Response Type** is **Redirect**.
- **Redirect Status · Optional**: How the redirect is treated: pick Permanent if the new address is forever, otherwise Temporary. Options: 301 Moved Permanently, 302 Found, 303 See Other, 307 Temporary Redirect, 308 Permanent Redirect. Default: 302 Found. Shows when **Response Type** is **Redirect**.
- **Response Headers · Optional**: Extra label-and-value pairs to include with the response (such as Content-Type: application/json). Shows when **Response Type** isn’t **Redirect**.

Source: https://docs.gorunner.io/apps/webhook