Webhooks

Einrichtung

So funktioniert Inbound

Wenn ein Inbound Webhook eine Anfrage empfängt, stellt er den Agenten-Run in die Warteschlange und gibt eine Antwort mit den Run-IDs zurück. Der Agent arbeitet im Hintergrund. Das eignet sich für Hintergrundverarbeitung, Ingestion mit hohem Volumen und ereignisgesteuerte Architekturen.

Antwortformat

{
  "status": "ok",
  "dispatched_to": 2,
  "run_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

Webhook URL und Secret abrufen

Die Webhook URL enthält die Verbindungs-ID; das Secret für den Header X-Connic-Secret wird beim Erstellen der Verbindung generiert. Die Authentifizierung ist standardmäßig aktiviert. Deaktiviere Require Authentication nur für einen bewusst nicht authentifizierten Endpoint.

1. Öffne im Bereich Agenten die Detailseite des Agenten
2. Füge über den Button + im Verbindungsflussdiagramm eine Webhook-Verbindung hinzu oder wähle eine vorhandene aus
3. Klicke auf das Augensymbol der Verbindung, um ihre Details zu öffnen
4. Kopiere Webhook URL und Secret aus den Verbindungsdetails

Authentifizierung

Schütze Webhooks mit Secret-basierter Authentifizierung. Inbound und Sync Webhooks erfordern dieses Secret standardmäßig. Deaktiviere Require Authentication nur, wenn sich Aufrufer nicht authentifizieren müssen.

Jeder Webhook besitzt einen eindeutigen Secret Key, der beim Erstellen generiert wird. Ist Require Authentication aktiviert, lässt sich das Secret auf drei Arten übermitteln:

• X-Connic-Secret Header (empfohlen) – Am sichersten; das Secret steht in den Headern
• Authorization: Bearer Header – Standardmäßiger Bearer Token im OAuth-Stil
• Query Parameter (?secret=...) – Weniger sicher; in Logs sichtbar

# X-Connic-Secret-Header verwenden (empfohlen)
curl -X POST <webhook-url> \
  -H "X-Connic-Secret: <your-secret-key>" \
  -d '{"message": "hallo"}'

# Authorization: Bearer-Header verwenden
curl -X POST <webhook-url> \
  -H "Authorization: Bearer <your-secret-key>" \
  -d '{"message": "hallo"}'

# Query-Parameter verwenden (weniger sicher)
curl -X POST "<webhook-url>?secret=<your-secret-key>" \
  -d '{"message": "hallo"}'

Fehlerantworten

Einrichtung

So funktioniert Outbound

Automatische Outbound-Webhooks senden Agent-Ergebnisse nach Abschluss eines Runs an eine externe URL. Agent-Tool- und Middleware-Outbound-Webhooks senden, wenn sie während eines Runs aufgerufen werden. Die Verbindung verwendet eine konfigurierte Ziel-URL, an die Connic die Ergebnisse per POST sendet. Leite ausgehende Anfragen an private Endpoints über eine Connic Bridge. Das eignet sich zum Senden von Ergebnissen an externe APIs, zur Integration von Drittanbieterdiensten und zum Aufbau von Ereignis-Pipelines.

Automatische Payload

Automatische Outbound-Verbindungen senden den Wrapper des abgeschlossenen Runs per POST. Bei bestehenden Verknüpfungen werden weiterhin alle abgeschlossenen Runs automatisch gesendet, solange ihr Modus oder Quellenfilter nicht geändert wird.

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "invoice-processor",
  "status": "completed",
  "output": "Der Rechnungsbetrag beträgt $1,234.56",
  "error": null,
  "started_at": "2024-01-15T10:30:00Z",
  "ended_at": "2024-01-15T10:30:05Z",
  "token_usage": {
    "input_tokens": 150,
    "output_tokens": 50,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 200
  }
}

Agent-Tool- und Middleware-Outbound-Verbindungen

Agent-Tool-Outbound-Verbindungen stellen einen bearbeitbaren Tool-Namen bereit, standardmäßig send_to_<connector_name>. Rufe Middleware-Outbound-Verbindungen mit send_connector(action_name, payload) unter ihrem konfigurierten Namen auf. Beide verwenden dasselbe von der Verbindung definierte Payload-Schema: Übermittle den JSON-Body unter payload.

{
  "payload": {
    "invoice_id": "inv_123",
    "status": "approved"
  }
}

Connic sendet den verschachtelten Wert per POST und verwendet URL, konfigurierte Header, HMAC-Signatur, Wiederholungsstrategie und Bridge-Routing der Verbindung. Diese Einstellungen werden dem Modell nicht offengelegt.

Jede Outbound-Webhook-Anfrage enthält eine HMAC-SHA256-Signatur. Prüfe sie, um die Echtheit der Anfragen sicherzustellen.

import hmac
import hashlib
import time

def verify_webhook(payload: bytes, signature: str, timestamp: str, secret: str) -> bool:
    """Signatur eines Connic Webhooks prüfen."""
    # Prüfen, ob der Zeitstempel zu alt ist (5-Minuten-Fenster)
    if abs(time.time() - int(timestamp)) > 300:
        return False

    # Signierte Payload erstellen
    signed_payload = f"{timestamp}.".encode() + payload

    # Erwartete Signatur berechnen
    expected = hmac.new(
        secret.encode(),
        signed_payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

# Verwendung in Flask
@app.route("/webhook", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Connic-Signature", "")
    timestamp = request.headers.get("X-Connic-Timestamp", "")

    if not verify_webhook(request.data, signature, timestamp, SIGNING_SECRET):
        return "Ungültige Signatur", 401

    # Webhook verarbeiten ...
    return "OK", 200

import crypto from 'crypto';

function verifyWebhook(payload, signature, timestamp, secret) {
  // Prüfen, ob der Zeitstempel zu alt ist (5-Minuten-Fenster)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    return false;
  }

  // Signierte Payload erstellen
  const signedPayload = `${timestamp}.${payload}`;

  // Erwartete Signatur berechnen
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// Verwendung in Express
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-connic-signature'];
  const timestamp = req.headers['x-connic-timestamp'];

  if (!verifyWebhook(req.body.toString(), signature, timestamp, SIGNING_SECRET)) {
    return res.status(401).send('Ungültige Signatur');
  }

  // Webhook verarbeiten ...
  res.send('OK');
});

So funktioniert Sync

Sync Webhooks warten auf den Abschluss des Agenten und geben das Ergebnis in derselben HTTP-Antwort zurück – ein klassisches Request-Response-Muster. Das eignet sich für REST-API-Integrationen, interaktive Anwendungen und kurz laufende Aufgaben.

Einrichtung

Antwortformat

{
  "status": "ok",
  "result": {
    "run_id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_name": "invoice-processor",
    "status": "completed",
    "output": "Der Rechnungsbetrag beträgt $1,234.56",
    "error": null
  }
}

Client-Beispiele

import requests

url = "<webhook-url>"
secret = "<your-secret-key>"

payload = {"query": "Wie ist der Status der Bestellung 123?"}
resp = requests.post(
    url,
    json=payload,
    headers={"X-Connic-Secret": secret},
    timeout=310,
)
resp.raise_for_status()
print(resp.json()["result"]["output"])

import fetch from "node-fetch";

const url = "<webhook-url>";
const secret = "<your-secret-key>";

const resp = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Connic-Secret": secret,
  },
  body: JSON.stringify({ query: "Fasse das neueste Ticket zusammen" }),
});

if (!resp.ok) throw new Error(await resp.text());
const data = await resp.json();
console.log(data.result.output);

Webhook URL und Secret abrufen

Die Webhook URL enthält die Verbindungs-ID; das Secret für den Header X-Connic-Secret wird beim Erstellen der Verbindung generiert. Die Authentifizierung ist standardmäßig aktiviert. Deaktiviere Require Authentication nur für einen bewusst nicht authentifizierten Endpoint.

1. Öffne im Bereich Agenten die Detailseite des Agenten
2. Füge über den Button + im Verbindungsflussdiagramm eine Webhook-Verbindung hinzu oder wähle eine vorhandene aus
3. Klicke auf das Augensymbol der Verbindung, um ihre Details zu öffnen
4. Kopiere Webhook URL und Secret aus den Verbindungsdetails

Authentifizierung

Schütze Webhooks mit Secret-basierter Authentifizierung. Inbound und Sync Webhooks erfordern dieses Secret standardmäßig. Deaktiviere Require Authentication nur, wenn sich Aufrufer nicht authentifizieren müssen.

Jeder Webhook besitzt einen eindeutigen Secret Key, der beim Erstellen generiert wird. Ist Require Authentication aktiviert, lässt sich das Secret auf drei Arten übermitteln:

• X-Connic-Secret Header (empfohlen) – Am sichersten; das Secret steht in den Headern
• Authorization: Bearer Header – Standardmäßiger Bearer Token im OAuth-Stil
• Query Parameter (?secret=...) – Weniger sicher; in Logs sichtbar

# X-Connic-Secret-Header verwenden (empfohlen)
curl -X POST <webhook-url> \
  -H "X-Connic-Secret: <your-secret-key>" \
  -d '{"message": "hallo"}'

# Authorization: Bearer-Header verwenden
curl -X POST <webhook-url> \
  -H "Authorization: Bearer <your-secret-key>" \
  -d '{"message": "hallo"}'

# Query-Parameter verwenden (weniger sicher)
curl -X POST "<webhook-url>?secret=<your-secret-key>" \
  -d '{"message": "hallo"}'

Fehlerantworten