ironclaw/docs/channels/webhook.mdx

---
title: HTTP Webhook
sidebarTitle: Webhook
description: 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
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
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
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
{
  "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
curl http://localhost:8080/jobs/{job_id} -H "X-Webhook-Secret: your-secret"
```

Response:
```json
{
  "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
# 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
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>