Webhook Format

Selu supports webhooks for integrating with external services. Inbound webhooks let outside systems send events into Selu (e.g. a CI pipeline notifying an agent). Outbound webhooks let Selu push events to your services (e.g. notifying Slack when a conversation finishes).

Inbound webhooks

External systems send HTTP POST requests to Selu’s inbound webhook endpoint.

Endpoint

POST /api/v1/webhooks/inbound/{webhook_id}

Each inbound webhook has a unique webhook_id generated when you create it via the dashboard or CLI (selu webhook create --direction inbound).

Payload format

{
  "event": "custom.build_complete",
  "timestamp": "2026-03-03T14:22:00Z",
  "source": "ci-pipeline",
  "data": {
    "repo": "selu-platform/web-search",
    "branch": "main",
    "commit": "a1b2c3d",
    "status": "success",
    "duration_seconds": 142
  }
}

Field	Type	Required	Description
`event`	`string`	Yes	Event type identifier. Use a dotted namespace (e.g. `custom.deploy_complete`).
`timestamp`	`string`	Yes	ISO 8601 timestamp of when the event occurred.
`source`	`string`	No	Identifier for the originating system.
`data`	`object`	Yes	Arbitrary payload. Passed to the agent as-is.

Authentication

Include the webhook secret in the X-Selu-Signature header. The value is an HMAC-SHA256 hex digest of the raw request body, computed with the secret shown when the webhook was created.

X-Selu-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Outbound webhooks

Selu sends HTTP POST requests to a URL you configure whenever a subscribed event occurs.

Subscribable events

Event	Description
`conversation.started`	A new conversation was created.
`conversation.completed`	A conversation was marked as finished.
`agent.installed`	A new agent was installed.
`agent.error`	An agent encountered a runtime error.
`capability.invoked`	A capability was invoked by an agent.

Payload format

{
  "webhook_id": "wh_outbound_abc123",
  "event": "conversation.completed",
  "timestamp": "2026-03-03T15:00:00Z",
  "data": {
    "conversation_id": "conv_abc123",
    "agent_name": "research-assistant",
    "channel": "telegram",
    "message_count": 8,
    "capabilities_used": ["web-search"],
    "duration_seconds": 45
  }
}

Retry policy

Selu retries failed deliveries (non-2xx responses) with exponential backoff: 10s, 30s, 90s, 270s. After 4 failed attempts, the delivery is marked as failed. You can view delivery history and manually retry from the dashboard under Settings → Webhooks.

# Inbound
selu webhook create --direction inbound --name "CI Notifications"

# Outbound
selu webhook create --direction outbound \
  --name "Slack Notifier" \
  --url https://example.com/hooks/selu \
  --events conversation.completed,agent.error

curl -X POST http://localhost:8080/api/v1/webhooks \
  -H "Authorization: Bearer $SELU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "outbound",
    "name": "Slack Notifier",
    "url": "https://example.com/hooks/selu",
    "events": ["conversation.completed", "agent.error"]
  }'