# Webhook blocks

Ask an external service to help decide an approval request.

A Webhook block asks an external service what to do with a request. The service can check its own records or apply rules your organization maintains elsewhere, then return an outcome to the pipeline.

The block belongs to an [approval pipeline](/docs/web-app/approval-pipelines) and references a shared [Webhook endpoint](/docs/web-app/webhook-endpoints). The endpoint owns the destination and signing secret; the block controls the call and the authority of its answer.

## Endpoints and allowed outcomes

**Webhook Endpoint** identifies the service to call. **The endpoint may answer** controls which outcomes it is allowed to return.

| Outcome | What happens |
| --- | --- |
| **Continue** | The request moves to the next block. |
| **Ask a human** | The pipeline stops for human review. |
| **Approve** | The request is approved automatically. |
| **Deny** | The request is denied automatically. |

The allowed outcomes control the service's authority. A response outside that set is an error and sends the request to human review.

Human-review outcomes use the block's **Escalation path**, or the pipeline default if none is specified. The block's **Reason** identifies the policy check.

## Inputs and delivery settings

The service always receives the tool, the MCP server it comes from when it has one, its arguments and the agent's identity. **Agent reasoning**, **Request context** and **Earlier block results** add optional information to that call.

**Attempt timeout** limits how long one attempt can take. **Attempts** is the total number of tries, including the first. Temporary delivery failures can be retried. Invalid answers and disallowed outcomes send the request to human review without retrying.

If no attempt produces an accepted answer, the request goes to human review.

### Example: A refund-policy service

Our **Refund policy demo** service decides whether a refund should be approved, denied or reviewed by Payments. We'll allow all four outcomes so it can also pass a request to a later block. The block will use **Payments review** for human review.

In Support assistant's pipeline, this replaces the final manual-review block. The organization $500 limit and the agent's small-refund approval remain before it.

We'll include **Request context** and leave the other optional inputs off. A five-second timeout and three attempts allow the initial call and up to two retries for temporary failures. The block's reason will be "Refund checked by the refund policy service."

![A Webhook block selecting Refund policy demo, allowed outcomes, timeout, attempts and Payments review](/images/docs/webhook-blocks/configuration-light.png)

Our block uses Refund policy demo and accepts all four outcomes.

## Webhook responses

A response contains an outcome and can include a reason. The outcome values are `approve`, `deny`, `human` for Ask a human, and `next` for Continue.

The service's reason appears in the delivery evidence, separately from the block's configured **Reason**. It can also return metadata for later blocks to use when the request continues.

```mermaid
flowchart TD
    request["Request reaches the Webhook block"] --> service["External service"]
    service -->|"Accepted approve or deny"| decision["Finish the request"]
    service -->|"Continue"| next["Run the next block"]
    service -->|"Ask a human"| human["Human review"]
    service -->|"No accepted answer"| human
```

### Example: A $75 refund response

Our $75 refund passes the organization limit and the small-refund block, so it reaches the service. The service's policy returns this response.

```json
{
  "outcome": "human",
  "reason": "Refunds over $20 need Payments review."
}
```

The block accepts `human` and has Payments review selected, so the request goes to that path. The webhook call succeeded; its answer is that a human should decide.

## Webhook testing

The pipeline's **Test request** sends a real webhook using the sample you provide. The call is marked as a preview. It creates no approval request and notifies no reviewers, but the receiving service still handles the call.

The test shows the endpoint, HTTP status, delivery time, response reason and final block outcome. Errors appear in the result. An earlier pipeline decision can stop a sample before the webhook runs.

An [endpoint test delivery](/docs/web-app/webhook-endpoints#test-deliveries) checks a saved destination directly, including a draft, without running a pipeline.

The [main page](/docs/web-app/approval-pipelines#pipeline-testing) includes a $75 sample for testing the refund-policy service. Testing also helps check how the service handles other outcomes and delivery failures. Use fictional data and an endpoint suitable for testing.