Board Webhooks - OpenClaw Mission Control

Overview

Board webhooks allow external systems to send events to boards. Each webhook has a unique URL endpoint that accepts POST requests. When a payload is received, it’s stored in board memory and the designated agent (or board lead) is notified.

List Board Webhooks

GET /api/v1/boards/{board_id}/webhooks

List all configured webhooks for a board.

Path Parameters

board_id

string (UUID)

required

The board ID to list webhooks for

Query Parameters

limit

integer

default:"50"

Maximum number of webhooks to return

offset

integer

default:"0"

Number of webhooks to skip

Response

items

array

Array of webhook configurations

string (UUID)

Unique webhook identifier

board_id

string (UUID)

Board this webhook belongs to

agent_id

string (UUID)

Specific agent to notify when webhook receives data. If null, notifies the board lead.

description

string

Human-readable description of what this webhook is for and how agents should handle it

enabled

boolean

Whether the webhook is currently accepting requests

endpoint_path

string

Relative URL path for this webhook (e.g., /api/v1/boards/{board_id}/webhooks/{webhook_id})

endpoint_url

string

Full URL for this webhook endpoint. May be null if base_url is not configured.

created_at

string (datetime)

When the webhook was created

updated_at

string (datetime)

When the webhook was last updated

Example Request

curl -X GET "https://api.example.com/api/v1/boards/123e4567-e89b-12d3-a456-426614174000/webhooks" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "items": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "board_id": "123e4567-e89b-12d3-a456-426614174000",
      "agent_id": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "description": "GitHub deployment webhook - create tasks for failed deployments",
      "enabled": true,
      "endpoint_path": "/api/v1/boards/123e4567-e89b-12d3-a456-426614174000/webhooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "endpoint_url": "https://api.example.com/api/v1/boards/123e4567-e89b-12d3-a456-426614174000/webhooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-03-01T10:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Create Board Webhook

POST /api/v1/boards/{board_id}/webhooks

Create a new webhook with a generated UUID endpoint.

Path Parameters

board_id

string (UUID)

required

The board ID to create the webhook for

Request Body

description

string

required

Human-readable description of the webhook’s purpose and how agents should handle incoming data. This is sent to agents with each webhook payload.Example: "GitHub deployment webhook - create tasks for failed deployments and notify team"

enabled

boolean

default:"true"

Whether the webhook should immediately accept requests

agent_id

string (UUID)

Specific agent to notify. If not provided, the board lead is notified. Agent must belong to this board.

Response

Returns the created webhook configuration including the generated endpoint URL.

string (UUID)

Unique webhook identifier (auto-generated)

board_id

string (UUID)

Board this webhook belongs to

agent_id

string (UUID)

Agent to notify

description

string

Webhook description

enabled

boolean

Whether webhook is enabled

endpoint_path

string

Relative URL path for webhook

endpoint_url

string

Full webhook URL

created_at

string (datetime)

Creation timestamp

updated_at

string (datetime)

Last update timestamp

Example Request

curl -X POST "https://api.example.com/api/v1/boards/123e4567-e89b-12d3-a456-426614174000/webhooks" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "GitHub deployment webhook - create tasks for failed deployments",
    "enabled": true
  }'

Example Response

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "board_id": "123e4567-e89b-12d3-a456-426614174000",
  "agent_id": null,
  "description": "GitHub deployment webhook - create tasks for failed deployments",
  "enabled": true,
  "endpoint_path": "/api/v1/boards/123e4567-e89b-12d3-a456-426614174000/webhooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "endpoint_url": "https://api.example.com/api/v1/boards/123e4567-e89b-12d3-a456-426614174000/webhooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "created_at": "2026-03-05T15:30:00Z",
  "updated_at": "2026-03-05T15:30:00Z"
}

Update Board Webhook

PATCH /api/v1/boards/{board_id}/webhooks/{webhook_id}

Update webhook description, enabled state, or target agent.

Path Parameters

board_id

string (UUID)

required

The board ID

webhook_id

string (UUID)

required

The webhook ID to update

Request Body

All fields are optional. Only include fields you want to change.

description

string

Updated webhook description

enabled

boolean

Enable or disable the webhook

agent_id

string (UUID)

Change the target agent. Agent must belong to this board.

Response

Returns the updated webhook configuration.

Example Request

curl -X PATCH "https://api.example.com/api/v1/boards/123e4567-e89b-12d3-a456-426614174000/webhooks/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "description": "GitHub deployment webhook - temporarily disabled for maintenance"
  }'

Delete Board Webhook

DELETE /api/v1/boards/{board_id}/webhooks/{webhook_id}

Delete a webhook and all its stored payload history.

Path Parameters

board_id

string (UUID)

required

The board ID

webhook_id

string (UUID)

required

The webhook ID to delete

Response

{
  "ok": true
}

Example Request

curl -X DELETE "https://api.example.com/api/v1/boards/123e4567-e89b-12d3-a456-426614174000/webhooks/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ingest Webhook Payload

POST /api/v1/boards/{board_id}/webhooks/{webhook_id}

Public endpoint - no authentication required. External systems post data here.

Path Parameters

board_id

string (UUID)

required

The board ID

webhook_id

string (UUID)

required

The webhook ID

Request Body

Accepts any valid JSON, plain text, or form data. The system automatically:

Captures the payload with headers (Content-Type, User-Agent, X-* headers) and source IP
Stores in board memory with tags ["webhook", "webhook:{webhook_id}", "payload:{payload_id}"]
Queues notification to the designated agent or board lead
Returns immediately with 202 Accepted

Response

Returns a 202 Accepted status with payload tracking IDs.

boolean

Always true for successful ingestion

board_id

string (UUID)

Board that received the webhook

webhook_id

string (UUID)

Webhook that received the payload

payload_id

string (UUID)

Unique ID for this payload instance (for later inspection)

Agent Notification

The target agent receives a message with:

Board and webhook identification
Payload preview
Instructions to triage and create/update tasks
Reference to the payload ID for inspection

Example Request - JSON Payload

curl -X POST "https://api.example.com/api/v1/boards/123e4567-e89b-12d3-a456-426614174000/webhooks/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: deployment_status" \
  -d '{
    "deployment": {
      "id": 12345,
      "environment": "production",
      "state": "failure"
    },
    "repository": {
      "name": "my-app",
      "url": "https://github.com/org/my-app"
    }
  }'

Example Response

{
  "ok": true,
  "board_id": "123e4567-e89b-12d3-a456-426614174000",
  "webhook_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "payload_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Error Responses

404 Not Found

Board or webhook does not exist

410 Gone

Webhook is disabled. Enable it via PATCH endpoint before sending data.

List Webhook Payloads

GET /api/v1/boards/{board_id}/webhooks/{webhook_id}/payloads

List stored payloads for a webhook (for inspection and debugging).

Path Parameters

board_id

string (UUID)

required

The board ID

webhook_id

string (UUID)

required

The webhook ID

Query Parameters

limit

integer

default:"50"

Maximum number of payloads to return

offset

integer

default:"0"

Number of payloads to skip

Response

items

array

Array of stored payloads, sorted by received date (most recent first)

string (UUID)

Unique payload identifier

board_id

string (UUID)

Board ID

webhook_id

string (UUID)

Webhook ID

payload

object | array | string | number | boolean

The parsed payload data. Type depends on content sent.

headers

object

Captured HTTP headers (Content-Type, User-Agent, X-* headers)

source_ip

string

IP address that sent the request

content_type

string

Content-Type header value

received_at

string (datetime)

When the payload was received

Example Request

curl -X GET "https://api.example.com/api/v1/boards/123e4567-e89b-12d3-a456-426614174000/webhooks/7c9e6679-7425-40de-944b-e07fc1f90ae7/payloads" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "items": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "board_id": "123e4567-e89b-12d3-a456-426614174000",
      "webhook_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "payload": {
        "deployment": {
          "id": 12345,
          "environment": "production",
          "state": "failure"
        },
        "repository": {
          "name": "my-app",
          "url": "https://github.com/org/my-app"
        }
      },
      "headers": {
        "content-type": "application/json",
        "user-agent": "GitHub-Hookshot/abc123",
        "x-github-event": "deployment_status"
      },
      "source_ip": "192.0.2.1",
      "content_type": "application/json",
      "received_at": "2026-03-05T15:30:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Get Single Webhook Payload

GET /api/v1/boards/{board_id}/webhooks/{webhook_id}/payloads/{payload_id}

Retrieve a single stored payload by ID.

Path Parameters

board_id

string (UUID)

required

The board ID

webhook_id

string (UUID)

required

The webhook ID

payload_id

string (UUID)

required

The payload ID to retrieve

Response

Returns a single payload object with the same structure as items in the list endpoint.

Example Request

curl -X GET "https://api.example.com/api/v1/boards/123e4567-e89b-12d3-a456-426614174000/webhooks/7c9e6679-7425-40de-944b-e07fc1f90ae7/payloads/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Authorization

All webhook configuration and payload inspection endpoints require authentication and board access:

List, Create, Update, Delete: Write access to the board
Get, List Payloads: Read access to the board
Ingest endpoint: No authentication required (public)

Authentication

Organizations

Boards

Tasks

Agents

Gateways

Approvals

Skills & Tags

Activity & Metrics

​Overview

​List Board Webhooks

​Path Parameters

​Query Parameters

​Response

​Example Request

​Example Response

​Create Board Webhook

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Update Board Webhook

​Path Parameters

​Request Body

​Response

​Example Request

​Delete Board Webhook

​Path Parameters

​Response

​Example Request

​Ingest Webhook Payload

​Path Parameters

​Request Body

​Response

​Agent Notification

​Example Request - JSON Payload

​Example Response

​Error Responses

​List Webhook Payloads

​Path Parameters

​Query Parameters

​Response

​Example Request

​Example Response

​Get Single Webhook Payload

​Path Parameters

​Response

​Example Request

​Authorization

Build docs developers (and LLMs) love

Overview

List Board Webhooks

Path Parameters

Query Parameters

Response

Example Request

Example Response

Create Board Webhook

Path Parameters

Request Body

Response

Example Request

Example Response

Update Board Webhook

Path Parameters

Request Body

Response

Example Request

Delete Board Webhook

Path Parameters

Response

Example Request

Ingest Webhook Payload

Path Parameters

Request Body

Response

Agent Notification

Example Request - JSON Payload

Example Response

Error Responses

List Webhook Payloads

Path Parameters

Query Parameters

Response

Example Request

Example Response

Get Single Webhook Payload

Path Parameters

Response

Example Request

Authorization