Webhook blocks

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 and references a shared Webhook endpoint. 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.

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."

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.

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.

{
  "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 checks a saved destination directly, including a draft, without running a pipeline.

The main page 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.