Webhooks API

profClaw handles webhooks in two directions: inbound (from GitHub, Jira, Linear to create tasks) and outbound (from profClaw to notify your systems when tasks complete).

Inbound Webhooks

Service	URL	Signature Header
GitHub	`POST /api/webhooks/github`	`X-Hub-Signature-256`
Jira	`POST /api/webhooks/jira`	`X-Hub-Signature`
Linear	`POST /api/webhooks/linear`	`Linear-Signature`

All inbound webhooks are signature-verified. Set GITHUB_WEBHOOK_SECRET, JIRA_WEBHOOK_SECRET, or LINEAR_WEBHOOK_SECRET as appropriate.

Verification failure

Requests that fail signature verification return:

HTTP 403
{ "error": "Invalid webhook signature" }

Outbound Webhook Registration

GET /api/webhooks

List registered outbound webhook endpoints.

curl http://localhost:3000/api/webhooks --cookie "profclaw_session=<token>"

Response 200

{
  "webhooks": [
    {
      "id": "wh_01",
      "url": "https://your-service.com/webhook",
      "events": ["task.completed", "task.failed"],
      "active": true,
      "secret": "wh_sec_*****",
      "createdAt": "2026-03-01T00:00:00Z",
      "lastDelivery": "2026-03-12T10:00:00Z",
      "deliveryCount": 42,
      "failureCount": 0
    }
  ]
}

POST /api/webhooks

curl -X POST http://localhost:3000/api/webhooks \
  -H "Content-Type: application/json" \
  --cookie "profclaw_session=<token>" \
  -d '{
    "url": "https://your-service.com/webhook",
    "events": ["task.completed", "task.failed"],
    "secret": "optional-signing-secret"
  }'

DELETE /api/webhooks/:id

Remove a webhook registration.

Outbound Event Types

Event	Payload Fields
`task.created`	`id`, `title`, `status`, `source`
`task.completed`	`id`, `title`, `result`, `duration`
`task.failed`	`id`, `title`, `error`, `attempts`
`task.cancelled`	`id`, `title`
`agent.started`	`taskId`, `agentType`
`agent.finished`	`taskId`, `agentType`, `output`

Delivery Format

{
  "id": "delivery_01",
  "event": "task.completed",
  "timestamp": "2026-03-12T10:30:00Z",
  "payload": {
    "id": "task_01",
    "title": "Fix login bug",
    "result": "Fixed the session cookie bug in auth-service.ts",
    "duration": 45230
  }
}

Outbound webhooks are signed with X-ProfClaw-Signature: sha256=<hmac> when a secret is provided.

Retry Policy

Failed deliveries are retried with exponential backoff:

Attempt	Delay
1	30 seconds
2	5 minutes
3	30 minutes
4	2 hours
5	12 hours

After 5 failed attempts, the webhook is marked as failing and deliveries pause. Re-activate with PATCH /api/webhooks/:id setting active: true.

Delivery Log

GET /api/webhooks/:id/deliveries?limit=20

Returns recent delivery attempts with status codes and response bodies.

Redeliver

POST /api/webhooks/:id/deliveries/:deliveryId/redeliver

Manually trigger redelivery of a specific event.

profclaw webhooks - Manage webhook endpoints from the CLI
Tasks API - Tasks trigger outbound webhook events
Integrations Overview - Configure inbound GitHub, Jira, and Linear webhooks
Security API - Audit log of inbound webhook processing

API Overview

Authentication

Chat

Agents

Tasks

Memory

Integrations

System

Inbound Webhooks

Verification failure

Outbound Webhook Registration

GET /api/webhooks

POST /api/webhooks

DELETE /api/webhooks/:id

Outbound Event Types

Delivery Format

Retry Policy

Delivery Log

Redeliver

​Inbound Webhooks

​Verification failure

​Outbound Webhook Registration

​GET /api/webhooks

​POST /api/webhooks

​DELETE /api/webhooks/:id

​Outbound Event Types

​Delivery Format

​Retry Policy

​Delivery Log

​Redeliver

​Related

Inbound Webhooks

Verification failure

Outbound Webhook Registration

GET /api/webhooks

POST /api/webhooks

DELETE /api/webhooks/:id

Outbound Event Types

Delivery Format

Retry Policy

Delivery Log

Redeliver

Related