Webhooks

Erhalten Sie Echtzeit-HTTP-Benachrichtigungen, wenn Ereignisse in BoundaryAI auftreten.

Übersicht

Webhooks ermöglichen es Ihnen, Echtzeit-Benachrichtigungen zu erhalten, wenn Ereignisse in BoundaryAI auftreten. Anstatt unsere API abzufragen, empfängt Ihr Server automatisch HTTP-POST-Anfragen.

Anwendungsfälle:

• Push-Inhalte mit Ihrem Data Warehouse synchronisieren

• Workflows auslösen, wenn Umfragen erstellt/veröffentlicht werden

• Echtzeit-Dashboards erstellen

• Integration mit Slack, Teams oder anderen Tools

Voraussetzungen

1. Administratorzugriff - Nur Organisationsadministratoren können Webhooks verwalten

2. HTTPS-Endpunkt - Ihre Webhook-URL muss HTTPS verwenden (HTTP nicht erlaubt)

3. Öffentliche URL - Die URL muss öffentlich zugänglich sein (kein localhost, keine privaten IPs oder internen Domains)

4. Antwortzeit - Ihr Endpunkt sollte innerhalb von 10 Sekunden antworten

Verfügbare Ereignisse

Ereignis	Beschreibung	Wann es ausgelöst wird
content.pushed	Inhalt wurde per API gepusht	Nach erfolgreichem /api/input/content/push oder /api/input/content/push/bulk
survey.created	Eine neue Umfrage wurde erstellt	Nach erfolgreichem /api/input/survey/create
survey.published	Eine Umfrage wurde veröffentlicht	Nach erfolgreichem /api/input/survey/publish
series.created	Eine neue Feedback-Gruppe wurde erstellt	Nach erfolgreichem /api/input/survey_series/create

Webhook-Payload

{
  "event": "content.pushed",
  "timestamp": "2025-01-15T10:30:00.000000Z",
  "data": {
    "survey_series_id": 123,
    "survey_id": 456,
    "question_id": 789,
    "lines_pushed": 50,
    "api_key_id": 1
  }
}

HTTP-Header

Jede Webhook-Anfrage enthält diese Header:

Header	Beschreibung	Beispiel
X-Boundary-Signature	HMAC-SHA256-Signatur zur Verifikation	sha256=abc123...
X-Boundary-Event	Der Ereignistyp, der diesen Webhook ausgelöst hat	content.pushed
Content-Type	Immer JSON	application/json
User-Agent	Identifiziert BoundaryAI als Absender	BoundaryAI-Webhook/1.0

Webhooks verwalten

Alle Endpunkte zur Verwaltung von Webhooks erfordern JWT-Authentifizierung (nicht API-Schlüssel).

Webhooks auflisten

GET /api/webhooks
Authorization: Bearer {JWT_TOKEN}

^Antwort

{
  "is_admin": true,
  "webhooks": [
    {
      "id": 1,
      "name": "Mein Webhook",
      "url": "https://example.com/webhook",
      "events": ["content.pushed", "survey.created"],
      "is_active": true,
      "failure_count": 0,
      "created_at": "2025-01-15T10:00:00+00:00",
      "last_triggered_at": null
    }
  ],
  "available_events": ["content.pushed", "survey.created", "survey.published", "series.created"]
}

Webhook erstellen

POST /api/webhooks
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "name": "Mein Webhook",
  "url": "https://example.com/webhook",
  "events": ["content.pushed", "survey.created"]
}

^Antwort

{
  "webhook": {
    "id": 1,
    "name": "Mein Webhook",
    "url": "https://example.com/webhook",
    "events": ["content.pushed", "survey.created"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2025-01-15T10:00:00+00:00",
    "last_triggered_at": null
  },
  "secret": "ngQCfdLY0Ykp0_OLrXlMhzPfYNo0WV1w9j4Imt1ddMM",
  "message": "Speichern Sie das Secret jetzt! Sie werden es nicht erneut sehen können."
}

⚠️ Wichtig: Speichern Sie das Secret sofort – es wird nur einmal angezeigt!

Webhook aktualisieren

PATCH /api/webhooks/{id}
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "name": "Aktualisierter Name",
  "events": ["content.pushed"],
  "is_active": true
}

^Antwort

{
  "webhook": {
    "id": 1,
    "name": "Aktualisierter Name",
    "url": "https://example.com/webhook",
    "events": ["content.pushed"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2025-01-15T10:00:00+00:00",
    "last_triggered_at": null
  }
}

Einzelner Webhook

GET /api/webhooks/{id}
Authorization: Bearer {JWT_TOKEN}

^Antwort

{
  "webhook": {
    "id": 1,
    "name": "Mein Webhook",
    "url": "https://example.com/webhook",
    "events": ["content.pushed"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2025-01-15T10:00:00+00:00",
    "last_triggered_at": "2025-01-15T12:00:00+00:00"
  }
}

Webhook löschen

DELETE /api/webhooks/{id}
Authorization: Bearer {JWT_TOKEN}

^Antwort

{
  "message": "Webhook erfolgreich gelöscht",
  "webhook_id": 1
}

Signaturen verifizieren

Immer verifizieren die Signatur, um zu bestätigen, dass der Webhook von BoundaryAI stammt:

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# Verwendung in Flask:
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Boundary-Signature')
    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    event = request.headers.get('X-Boundary-Event')
    data = request.json
    # Verarbeiten Sie den Webhook...
    return 'OK', 200

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

// Verwendung in Express:
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-boundary-signature'];
  if (!verifyWebhook(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.headers['x-boundary-event'];
  const data = JSON.parse(req.body);
  // Verarbeiten Sie den Webhook...
  res.status(200).send('OK');
});

Wiederholungsrichtlinie

Wenn Ihr Endpunkt fehlschlägt, versuchen wir es mit exponentiellem Backoff erneut:

Versuch	Verzögerung
1. Wiederholung	1 Minute
2. Wiederholung	5 Minuten
3. Wiederholung	15 Minuten

Nach 10 aufeinanderfolgenden Fehlern, wird der Webhook automatisch deaktiviert.

---

Fehlerreferenz

Fehler-Antwortformat

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Für Menschen lesbare Beschreibung",
    "details": { }
  }
}

Fehlercodes

Authentifizierungsfehler (4xx)

Code	HTTP	Beschreibung	Lösung
MISSING_AUTH	401	Kein Authorization-Header	Hinzufügen Authorization: Bearer {key}
INVALID_AUTH_FORMAT	401	Fehlerhafter Header	Verwenden Sie Bearer {key} Format
INVALID_TOKEN	401	Schlüssel existiert nicht oder falsches Format	Überprüfen Sie den Schlüssel, bei Bedarf neuen erstellen
REVOKED_KEY	401	Schlüssel wurde widerrufen	Erstellen Sie einen neuen API-Schlüssel

Berechtigungsfehler (4xx)

Code	HTTP	Beschreibung	Lösung
INSUFFICIENT_PERMISSION	403	Schlüssel hat nicht die erforderliche Berechtigung	Verwenden Sie einen Schlüssel mit korrekter Berechtigung
FORBIDDEN	403	Ressource gehört zu einer anderen Organisation	Prüfen Sie, ob die IDs korrekt sind

Ressourcenfehler (4xx)

Code	HTTP	Beschreibung	Lösung
SURVEY_SERIES_NOT_FOUND	404	Feedback-Gruppe existiert nicht	Überprüfen Sie survey_series_id
SURVEY_NOT_FOUND	404	Datenquelle existiert nicht	Überprüfen Sie survey_id
QUESTION_NOT_FOUND	404	Frage existiert nicht	Überprüfen Sie question_id

Validierungsfehler (4xx)

Code	HTTP	Beschreibung	Lösung
VALIDATION_ERROR	400	Ungültige Anfragedaten	Überprüfen Sie details für spezifische Felder
INVALID_QUESTION_TYPE	400	Text wird an eine Nicht-Text-Frage gepusht	Verwenden Sie eine Frage mit accepts_text: true

Rate- & Quota-Fehler (4xx)

Code	HTTP	Beschreibung	Lösung
RATE_LIMITED	429	Zu viele Anfragen	Warten Sie auf Retry-After Sekunden
INSUFFICIENT_APS	402	Nicht genügend Analysepunkte	Kaufen Sie mehr APS oder verwenden Sie Test- Schlüssel