Skip to main content
The HTTP Webhook channel provides a REST API for integrating external services with IronClaw.
If you haven’t set up your agent yet, follow our Quickstart guide

​
Enabling Webhooks

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

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.

​
Shared Secret Validation

Configure a webhook secret to validate requests: 
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

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

{
  "job_id": "uuid",
  "status": "queued"
}

​
Payload Fields

FieldTypeRequiredDescription
user_idstringYesUser identifier
messagestringYesMessage content
conversation_idstringNoContinue existing conversation
metadataobjectNoArbitrary metadata

​
Response Fields

FieldTypeDescription
job_idstringJob UUID for status checking
statusstringqueued, running, completed
responsestringAgent response (when complete)

​
Checking Status

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

StatusMeaning
400Invalid request body
401Missing or invalid secret
429Rate limit exceeded
500Server error

​
Example Integrations

​
GitHub Webhook

Configure GitHub to send events to your IronClaw webhook URL: 
# 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

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

  • Check IronClaw is running
  • Verify HTTP_PORT is correct
  • Check firewall: sudo ufw allow 8080
  • Include X-Webhook-Secret header
  • Verify secret matches configuration
  • Rate limit: 60 requests/minute
  • Implement exponential backoff
  • Check logs: RUST_LOG=ironclaw=debug ironclaw run
  • Verify JSON format
  • Check user_id is valid