Skip to content
Skip to content

Webhooks PRO

Webhooks let you push real-time event notifications from ClawHQ to any HTTP endpoint. React to messages, agent deployments, channel changes, tickets, and API requests instantly — without polling.

Event Types

ClawHQ supports nine event types. When you create a webhook, you select which events it should receive. Each event delivers a JSON payload to your endpoint.

message.received

Fired when a user sends a message to any of your agents.

{
  "event": "message.received",
  "timestamp": "2026-03-16T14:30:00Z",
  "data": {
    "message_id": "msg_abc123",
    "channel": "web-chat",
    "agent": "support-bot",
    "content": "How do I reset my password?",
    "user_id": "usr_xyz789"
  }
}

message.sent

Fired when an agent sends a response to a user.

{
  "event": "message.sent",
  "timestamp": "2026-03-16T14:30:02Z",
  "data": {
    "message_id": "msg_def456",
    "channel": "web-chat",
    "agent": "support-bot",
    "content": "You can reset your password from the account settings page...",
    "response_time_ms": 1850
  }
}

agent.deployed

Fired when an agent is deployed to your VPS.

{
  "event": "agent.deployed",
  "timestamp": "2026-03-16T15:00:00Z",
  "data": {
    "agent_name": "sales-assistant",
    "deployed_by": "admin@company.com"
  }
}

agent.undeployed

Fired when an agent is removed from your VPS.

{
  "event": "agent.undeployed",
  "timestamp": "2026-03-16T15:05:00Z",
  "data": {
    "agent_name": "old-bot",
    "undeployed_by": "admin@company.com"
  }
}

channel.connected

Fired when a new channel is connected to your instance.

{
  "event": "channel.connected",
  "timestamp": "2026-03-16T16:00:00Z",
  "data": {
    "channel_type": "slack",
    "channel_name": "#customer-support"
  }
}

channel.disconnected

Fired when a channel is disconnected.

{
  "event": "channel.disconnected",
  "timestamp": "2026-03-16T16:30:00Z",
  "data": {
    "channel_type": "discord",
    "channel_name": "help-desk",
    "reason": "manual"
  }
}

ticket.created

Fired when a new support ticket is opened.

{
  "event": "ticket.created",
  "timestamp": "2026-03-16T17:00:00Z",
  "data": {
    "ticket_id": "tkt_001",
    "subject": "Agent not responding",
    "priority": "high",
    "created_by": "user@example.com"
  }
}

ticket.resolved

Fired when a support ticket is marked as resolved.

{
  "event": "ticket.resolved",
  "timestamp": "2026-03-16T18:00:00Z",
  "data": {
    "ticket_id": "tkt_001",
    "subject": "Agent not responding",
    "resolved_by": "admin@company.com",
    "resolution_time_hours": 1.0
  }
}

api.request

Fired when an API request is made to your instance via an API key.

{
  "event": "api.request",
  "timestamp": "2026-03-16T19:00:00Z",
  "data": {
    "method": "POST",
    "path": "/v1/chat",
    "api_key_name": "production-key",
    "status_code": 200,
    "latency_ms": 320
  }
}

HMAC Signature Verification

Every webhook delivery includes an X-ClawHQ-Signature header and an X-ClawHQ-Timestamp header. Together, these allow you to verify that the payload was sent by ClawHQ and has not been tampered with in transit.

The signature is computed over a concatenation of the delivery timestamp and the raw request body, separated by a period: timestamp.body. To verify:

  1. Read the X-ClawHQ-Timestamp header value
  2. Read the raw request body (do not parse it first)
  3. Concatenate the timestamp, a literal period (.), and the raw body to form the signed payload: {timestamp}.{body}
  4. Compute the HMAC-SHA256 hash of the signed payload using your webhook's signing secret as the key
  5. Compare the computed hash with the value in the X-ClawHQ-Signature header using a constant-time comparison
  6. If they match, the payload is authentic. If not, reject the request.
Security note: Always verify the HMAC signature before processing webhook payloads. This protects against spoofed requests from unauthorized sources. Use a constant-time comparison function to prevent timing attacks.

Automatic Retries

If your endpoint returns a non-2xx status code or fails to respond within 10 seconds, ClawHQ will automatically retry the delivery. The retry schedule uses exponential backoff:

  • Retry 1 — 30 seconds after the initial failure
  • Retry 2 — 5 minutes after the first retry
  • Retry 3 — 30 minutes after the second retry

After three failed retries, the delivery is marked as permanently failed. You can view failed deliveries in the delivery log and manually re-trigger them if needed.

Circuit Breaker

If a webhook endpoint fails 10 consecutive deliveries, ClawHQ automatically pauses that webhook to prevent further failed attempts from consuming resources. A paused webhook stops receiving events until you manually re-enable it.

When a circuit breaker trips, you receive a notification in the dashboard. Fix the underlying issue with your endpoint, then re-enable the webhook from the Webhooks management page. ClawHQ will send a test ping to verify the endpoint is responding before resuming event delivery.

Webhook Templates

Pre-configured templates make it easy to set up webhooks for popular services:

  • Slack — Sends formatted messages to a Slack channel using incoming webhook URLs. Events are formatted with rich Slack blocks including event type, timestamp, and relevant data fields.
  • Discord — Posts embed-formatted messages to a Discord channel via webhook URL. Includes color-coded embeds based on event type.
  • Zapier — Connects to Zapier catch hooks for integration with 5,000+ apps. The payload format is optimized for Zapier's data mapping.

Select a template when creating a new webhook, and the URL format and payload transformation are pre-configured. You can customize any template after creation.

Delivery Statistics

Each webhook has its own delivery statistics panel showing:

  • Success rate — Percentage of deliveries that received a 2xx response
  • Average latency — Mean time between sending the payload and receiving the response
  • Total deliveries — Count of all delivery attempts (including retries)
  • Last delivery — Timestamp and status of the most recent delivery

Delivery Log Viewer

The delivery log records every delivery attempt for every webhook. Each entry shows:

  • Event type and timestamp
  • HTTP status code returned by your endpoint
  • Response body (first 1KB)
  • Request duration in milliseconds
  • Whether the delivery was a retry and which attempt number

Use the delivery log to debug integration issues. If your endpoint is returning errors, the log shows exactly what was sent and what was received, making it easy to identify payload parsing issues, authentication problems, or endpoint misconfigurations.

SSRF Protection

ClawHQ validates all webhook destination URLs to prevent Server-Side Request Forgery (SSRF) attacks. Webhook URLs cannot point to private IP ranges, localhost, or internal network addresses. This protects your infrastructure from being used as a proxy for unauthorized internal requests.

Tip: Use the "Test" button on any webhook to send a sample payload to your endpoint without waiting for a real event. This is the fastest way to verify your integration is working correctly.

Related Documentation