Webhooks

Webhooks let external systems trigger SwarmClaw over HTTP.

Use them for event-driven workflows such as:

  • GitHub pushes
  • release notifications
  • CI status changes
  • custom automation hooks

What a Webhook Does

A webhook definition stores:

  • name
  • source label
  • event filters
  • target agent
  • optional secret
  • enabled or disabled state

When a matching request arrives, SwarmClaw records delivery history and routes the payload into the configured agent workflow.

Authentication

If a webhook has a secret, send it with:

  • the x-webhook-secret header
  • or the secret query parameter

Invalid secrets are rejected and logged in webhook history.

Delivery History

Each webhook keeps delivery history so operators can inspect:

  • success vs error status
  • payload summary
  • timestamps
  • validation failures such as bad secrets

API

  • GET /api/webhooks
  • POST /api/webhooks
  • GET /api/webhooks/:id
  • PUT /api/webhooks/:id
  • DELETE /api/webhooks/:id
  • POST /api/webhooks/:id
  • GET /api/webhooks/:id/history

CLI Examples

swarmclaw webhooks list
swarmclaw webhooks create --data '{"name":"GitHub Push","source":"github","events":["push"],"agentId":"<agentId>","secret":"my-secret"}'
swarmclaw webhooks trigger <webhookId> --payload '{"ref":"refs/heads/main"}'
swarmclaw webhooks history <webhookId>