> For the complete documentation index, see [llms.txt](https://whitepaper.aitech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.aitech.io/agentforge/yaml/yaml-schema/webhook.md).

# webhook

### Schema Definition

```yaml
type: object
required:
  - type
  - name
properties:
  type:
    type: string
    enum: [webhook]
    description: Block type identifier
  name:
    type: string
    description: Display name for this webhook block
  inputs:
    type: object
    properties:
      webhookConfig:
        type: object
        description: Webhook configuration settings
        properties:
          enabled:
            type: boolean
            description: Whether the webhook is active
            default: true
          secret:
            type: string
            description: Secret key for webhook verification
          headers:
            type: array
            description: Expected headers for validation
            items:
              type: object
              properties:
                key:
                  type: string
                  description: Header name
                value:
                  type: string
                  description: Expected header value
          methods:
            type: array
            description: Allowed HTTP methods
            items:
              type: string
              enum: [GET, POST, PUT, DELETE, PATCH]
            default: [POST]
      responseConfig:
        type: object
        description: Response configuration for the webhook
        properties:
          status:
            type: number
            description: HTTP status code to return
            default: 200
            minimum: 100
            maximum: 599
          headers:
            type: array
            description: Response headers
            items:
              type: object
              properties:
                key:
                  type: string
                  description: Header name
                value:
                  type: string
                  description: Header value
          body:
            type: string
            description: Response body content
  connections:
    type: object
    properties:
      success:
        type: string
        description: Target block ID for successful webhook processing
      error:
        type: string
        description: Target block ID for error handling
```

### Connection Configuration

Connections define where the workflow goes based on webhook processing:

```yaml
connections:
  success: <string>                     # Target block ID for successful processing
  error: <string>                       # Target block ID for error handling (optional)
```

### Examples

#### Basic Webhook Trigger

```yaml
github-webhook:
  type: webhook
  name: "GitHub Webhook"
  inputs:
    webhookConfig:
      enabled: true
      secret: "{{GITHUB_WEBHOOK_SECRET}}"
      methods: [POST]
      headers:
        - key: "X-GitHub-Event"
          value: "push"
    responseConfig:
      status: 200
      body: |
        {
          "message": "Webhook received successfully",
          "timestamp": "{{new Date().toISOString()}}"
        }
  connections:
    success: process-github-event
    error: webhook-error-handler
```

#### Slack Event Webhook

```yaml
slack-events:
  type: webhook
  name: "Slack Events"
  inputs:
    webhookConfig:
      enabled: true
      secret: "{{SLACK_SIGNING_SECRET}}"
      methods: [POST]
      headers:
        - key: "Content-Type"
          value: "application/json"
    responseConfig:
      status: 200
      headers:
        - key: "Content-Type"
          value: "application/json"
      body: |
        {
          "challenge": "<webhook.challenge>"
        }
  connections:
    success: handle-slack-event
```

#### Payment Webhook (Stripe)

```yaml
stripe-webhook:
  type: webhook
  name: "Stripe Payment Webhook"
  inputs:
    webhookConfig:
      enabled: true
      secret: "{{STRIPE_WEBHOOK_SECRET}}"
      methods: [POST]
      headers:
        - key: "Stripe-Signature"
          value: "*"
    responseConfig:
      status: 200
      headers:
        - key: "Content-Type"
          value: "application/json"
      body: |
        {
          "received": true
        }
  connections:
    success: process-payment-event
    error: payment-webhook-error
```

#### Generic API Webhook

```yaml
api-webhook:
  type: webhook
  name: "API Webhook"
  inputs:
    webhookConfig:
      enabled: true
      methods: [POST, PUT]
      headers:
        - key: "Authorization"
          value: "Bearer {{WEBHOOK_API_KEY}}"
        - key: "Content-Type"
          value: "application/json"
    responseConfig:
      status: 202
      headers:
        - key: "Content-Type"
          value: "application/json"
        - key: "X-Processed-By"
          value: "Forge"
      body: |
        {
          "status": "accepted",
          "id": "{{Math.random().toString(36).substr(2, 9)}}",
          "received_at": "{{new Date().toISOString()}}"
        }
  connections:
    success: process-webhook-data
```

#### Multi-Method Webhook

```yaml
crud-webhook:
  type: webhook
  name: "CRUD Webhook"
  inputs:
    webhookConfig:
      enabled: true
      methods: [GET, POST, PUT, DELETE]
      headers:
        - key: "X-API-Key"
          value: "{{CRUD_API_KEY}}"
    responseConfig:
      status: 200
      headers:
        - key: "Content-Type"
          value: "application/json"
      body: |
        {
          "method": "<webhook.method>",
          "processed": true,
          "timestamp": "{{new Date().toISOString()}}"
        }
  connections:
    success: route-by-method
```

### Webhook Variables

Inside webhook-triggered workflows, these special variables are available:

```yaml
# Available in blocks after the webhook
<webhook.payload>               # Full request payload/body
<webhook.headers>               # Request headers
<webhook.method>                # HTTP method used
<webhook.query>                 # Query parameters
<webhook.path>                  # Request path
<webhook.challenge>             # Challenge parameter (for verification)
```

### Output References

After a webhook processes a request, you can reference its data:

```yaml
# In subsequent blocks
process-webhook:
  inputs:
    payload: <webhook-name.payload>      # Request payload
    headers: <webhook-name.headers>      # Request headers
    method: <webhook-name.method>        # HTTP method
```

### Security Best Practices

* Always use webhook secrets for verification
* Validate expected headers and methods
* Implement proper error handling
* Use HTTPS endpoints in production
* Monitor webhook activity and failures
* Set appropriate response timeouts
* Validate payload structure before processing


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://whitepaper.aitech.io/agentforge/yaml/yaml-schema/webhook.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.