Webhook-Format

Selu unterstützt Webhooks für Integrationen mit externen Diensten. Eingehende Webhooks erlauben es externen Systemen, Ereignisse an Selu zu senden, etwa wenn eine CI-Pipeline einen Agenten benachrichtigt. Ausgehende Webhooks erlauben es Selu, Ereignisse an deine eigenen Dienste zu schicken, zum Beispiel an Slack, wenn ein Gespräch abgeschlossen ist.

Eingehende Webhooks

Externe Systeme senden HTTP-POST-Anfragen an den Endpunkt für eingehende Webhooks von Selu.

Endpunkt

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

Jeder eingehende Webhook hat eine eindeutige webhook_id, die erzeugt wird, wenn du ihn über Dashboard oder CLI mit selu webhook create --direction inbound anlegst.

Payload-Format

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

Feld	Typ	Erforderlich	Beschreibung
event	string	Ja	Bezeichner des Ereignistyps. Verwende einen Namensraum mit Punkten, etwa custom.deploy_complete.
timestamp	string	Ja	ISO-8601-Zeitstempel des Ereignisses
source	string	Nein	Kennung des Ursprungssystems
data	object	Ja	Beliebiges Payload. Es wird unverändert an den Agenten weitergegeben.

Authentifizierung

Übermittle das Webhook-Secret im Header X-Selu-Signature. Der Wert ist ein HMAC-SHA256-Hash des rohen Request-Bodys in Hex-Form, berechnet mit dem Secret, das beim Erstellen des Webhooks angezeigt wurde.

X-Selu-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Ausgehende Webhooks

Wenn ein abonnierter Event-Typ eintritt, sendet Selu HTTP-POST-Anfragen an eine von dir konfigurierte URL.

Abonnierbare Ereignisse

Ereignis	Beschreibung
conversation.started	Ein neues Gespräch wurde angelegt
conversation.completed	Ein Gespräch wurde als abgeschlossen markiert
agent.installed	Ein neuer Agent wurde installiert
agent.error	Bei einem Agenten ist ein Laufzeitfehler aufgetreten
capability.invoked	Eine Capability wurde von einem Agenten aufgerufen

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-Richtlinie

Selu versucht fehlgeschlagene Zustellungen, also Antworten ohne 2xx-Status, mit exponentiellem Backoff erneut: nach 10 Sekunden, 30 Sekunden, 90 Sekunden und 270 Sekunden. Nach vier Fehlversuchen wird die Zustellung als fehlgeschlagen markiert. Im Dashboard unter Settings → Webhooks kannst du den Zustellungsverlauf ansehen und manuell erneut auslösen.

Tipp

Nutze selu webhook test --id wh_outbound_abc123, um ein synthetisches Test-Event an deinen Endpunkt zu schicken und deine Integration zu prüfen.

Webhooks erstellen

CLI

# 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

REST-API

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"]
  }'