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

# HTTP Webhook

> REST API for external integrations

The HTTP Webhook channel provides a REST API for integrating external services with IronClaw.

<Note>
  If you haven't set up your agent yet, follow our [Quickstart guide](../quickstart)
</Note>

***

## Enabling Webhooks

```bash theme={null}
export HTTP_ENABLED=true
export HTTP_HOST=0.0.0.0
export HTTP_PORT=8080
export HTTP_WEBHOOK_SECRET=your-secret
```

Or during onboarding:

```
Step 6: Channel Configuration
→ Select "HTTP Webhook"
→ Port: 8080
```

***

## Security

<Warning>
  The HTTP webhook binds to `0.0.0.0:8080` by default. If you don't need external webhook delivery, set `HTTP_HOST=127.0.0.1`.
</Warning>

### Shared Secret Validation

Configure a webhook secret to validate requests:

```bash theme={null}
export HTTP_WEBHOOK_SECRET="your-secret-here"
```

The secret is sent in the `X-Webhook-Secret` header.

### Rate Limiting

* **Body size**: 64 KB maximum
* **Rate**: 60 requests per minute per IP

***

## Sending Messages

### Request Format

```bash theme={null}
curl -X POST http://localhost:8080/webhook \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-secret" \
  -d '{
    "user_id": "default",
    "message": "Hello, IronClaw!"
  }'
```

### Response Format

```json theme={null}
{
  "job_id": "uuid",
  "status": "queued"
}
```

***

## Payload Fields

| Field             | Type   | Required | Description                    |
| ----------------- | ------ | -------- | ------------------------------ |
| `user_id`         | string | Yes      | User identifier                |
| `message`         | string | Yes      | Message content                |
| `conversation_id` | string | No       | Continue existing conversation |
| `metadata`        | object | No       | Arbitrary metadata             |

## Response Fields

| Field      | Type   | Description                      |
| ---------- | ------ | -------------------------------- |
| `job_id`   | string | Job UUID for status checking     |
| `status`   | string | `queued`, `running`, `completed` |
| `response` | string | Agent response (when complete)   |

***

## Checking Status

```bash theme={null}
curl http://localhost:8080/jobs/{job_id} -H "X-Webhook-Secret: your-secret"
```

Response:

```json theme={null}
{
  "id": "uuid",
  "status": "completed",
  "response": "Hello! How can I help?",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:05Z"
}
```

***

## Error Responses

| Status | Meaning                   |
| ------ | ------------------------- |
| `400`  | Invalid request body      |
| `401`  | Missing or invalid secret |
| `429`  | Rate limit exceeded       |
| `500`  | Server error              |

***

## Example Integrations

### GitHub Webhook

Configure GitHub to send events to your IronClaw webhook URL:

```bash theme={null}
# GitHub webhook URL
https://your-server:8080/webhook

# Secret: your configured HTTP_WEBHOOK_SECRET
```

### Zapier

Use Zapier's Webhook action to send events to IronClaw.

### Custom Script

```python theme={null}
import requests

response = requests.post(
    "http://localhost:8080/webhook",
    headers={"X-Webhook-Secret": "your-secret"},
    json={"user_id": "automation", "message": "Process this data"}
)

print(response.json()["job_id"])
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection refused" icon="x-circle">
    * Check IronClaw is running
    * Verify `HTTP_PORT` is correct
    * Check firewall: `sudo ufw allow 8080`
  </Accordion>

  <Accordion title="401 Unauthorized" icon="key">
    * Include `X-Webhook-Secret` header
    * Verify secret matches configuration
  </Accordion>

  <Accordion title="429 Too Many Requests" icon="clock">
    * Rate limit: 60 requests/minute
    * Implement exponential backoff
  </Accordion>

  <Accordion title="Messages not processed" icon="message-circle">
    * Check logs: `RUST_LOG=ironclaw=debug ironclaw run`
    * Verify JSON format
    * Check `user_id` is valid
  </Accordion>
</AccordionGroup>