> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contextual.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Execute HTTP webhook calls in Agent Composer workflows

## Description

`WebhookStep` enables your agents to make HTTP calls to external APIs and services. Use webhooks to trigger actions, send notifications, update external systems, or retrieve data from REST APIs.

## WebhookStep

```yaml theme={null}
webhook:
  type: WebhookStep
  config:
    webhook_url: "https://api.example.com/endpoint"
    method: POST
    auth_token: "${API_TOKEN}"
    timeout: 30
  input_mapping:
    context_data: data_node#output
```

## Configuration Parameters

| Parameter        | Type         | Required | Default          | Description                                 |
| ---------------- | ------------ | -------- | ---------------- | ------------------------------------------- |
| `webhook_url`    | `str`        | Yes      | -                | The URL to call                             |
| `method`         | `HttpMethod` | No       | `POST`           | HTTP method (GET, POST, PUT, DELETE, PATCH) |
| `auth_token`     | `str`        | No       | -                | Bearer token for authentication             |
| `timeout`        | `int`        | No       | `30`             | Request timeout in seconds                  |
| `retries`        | `int`        | No       | `2`              | Number of retry attempts                    |
| `static_headers` | `Dict`       | No       | -                | Additional HTTP headers                     |
| `webhook_name`   | `str`        | No       | `"webhook-step"` | Identifier for logging                      |

## HTTP Methods

```yaml theme={null}
# GET request
get_data:
  type: WebhookStep
  config:
    webhook_url: "https://api.example.com/users/${user_id}"
    method: GET
    auth_token: "${API_TOKEN}"

# POST request
create_ticket:
  type: WebhookStep
  config:
    webhook_url: "https://api.example.com/tickets"
    method: POST
    auth_token: "${API_TOKEN}"
  input_mapping:
    context_data: ticket_data#output

# PUT request
update_record:
  type: WebhookStep
  config:
    webhook_url: "https://api.example.com/records/${record_id}"
    method: PUT
    auth_token: "${API_TOKEN}"
  input_mapping:
    context_data: updated_data#output
```

## Authentication

### Bearer Token

```yaml theme={null}
config:
  auth_token: "${API_TOKEN}"
```

### Custom Headers

```yaml theme={null}
config:
  static_headers:
    Authorization: "Basic ${ENCODED_CREDENTIALS}"
    X-API-Key: "${API_KEY}"
    Content-Type: "application/json"
```

## Input Data

The `context_data` input is sent as the request body for POST/PUT/PATCH requests:

```yaml theme={null}
nodes:
  # Prepare the data to send
  prepare_data:
    type: JSONCreatorStep
    config:
      schema: '{"customer_id": $customer_id, "message": $message, "priority": "high"}'
    input_mapping:
      customer_id: extract#customer_id
      message: generate#response

  # Send via webhook
  send_notification:
    type: WebhookStep
    config:
      webhook_url: "https://api.example.com/notifications"
      method: POST
      auth_token: "${API_TOKEN}"
    input_mapping:
      context_data: prepare_data#json
```

## Outputs

| Output           | Type                       | Description                        |
| ---------------- | -------------------------- | ---------------------------------- |
| `webhook_result` | `Optional[Dict[str, Any]]` | The JSON response from the webhook |

## Example: Trigger External Action

```yaml theme={null}
nodes:
  # Generate a response
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query
      retrievals: search#retrievals

  # Log the interaction to an external system
  log_interaction:
    type: WebhookStep
    config:
      webhook_url: "https://analytics.example.com/log"
      method: POST
      auth_token: "${ANALYTICS_TOKEN}"
      static_headers:
        X-Source: "contextual-agent"
    input_mapping:
      context_data: interaction_data#json

  __outputs__:
    type: output
    input_mapping:
      response: generate#response
```

## Example: Fetch External Data

```yaml theme={null}
nodes:
  # Get real-time data from external API
  fetch_prices:
    type: WebhookStep
    config:
      webhook_url: "https://api.pricing.example.com/current"
      method: GET
      auth_token: "${PRICING_TOKEN}"
      timeout: 10

  # Use the data in generation
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query
      retrievals: search#retrievals
      pricing_data: fetch_prices#webhook_result
```

## Error Handling

WebhookStep includes automatic retry logic. Configure retries and timeout:

```yaml theme={null}
config:
  webhook_url: "https://api.example.com/endpoint"
  timeout: 60        # Wait up to 60 seconds
  retries: 3         # Retry up to 3 times on failure
```

## Related

* [MCP Integration](/reference/ac-mcp-integration)
* [Code Execution](/reference/ac-code-execution)
* [Tools Configuration](/reference/ac-tools-config)