Webhooks

Einrichtung

1. 1

   Verbindung erstellen

   Öffne den Agenten, klicke im Verbindungsflussdiagramm auf Add inbound connector, dann auf Create New Connector und wähle HTTP Webhook.

2. 2

   Inbound (Fire & Forget) auswählen und Zugangsdaten kopieren

   Wähle den Mode und klicke auf Create. Der Detail-Drawer öffnet sich automatisch und zeigt unter Configuration die Webhook URL und das Secret. Um sie später anzuzeigen, bewege den Mauszeiger im Verbindungsflussdiagramm über die Verbindung und klicke auf das Augensymbol.

3. 3

   Anfragen senden

   Sende Anfragen aus der Anwendung an die URL. Wenn die Verbindungsauthentifizierung aktiviert ist, übermittle das Secret im Header X-Connic-Secret.

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. 1

   Öffne im Bereich Agenten die Detailseite des Agenten

2. 2

   Füge über den Button + im Verbindungsflussdiagramm eine Webhook-Verbindung hinzu oder wähle eine vorhandene aus

3. 3

   Klicke auf das Augensymbol der Verbindung, um ihre Details zu öffnen

4. 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"}'

Absender prüfen

Manche Absender signieren ihre Anfragen, etwa mit einem HMAC-Signatur-Header oder einem JWT in Authorization. Jeder Webhook-Run enthält die ursprüngliche Anfrage in context["request"], damit Middleware die Signatur prüfen kann, bevor der Agent läuft: Methode, Header mit kleingeschriebenen Namen, Query-Parameter und den unveränderten Body als body_base64.

# context["request"] in Middleware, Tools und Hooks
{
    "method": "POST",
    "headers": {"content-type": "application/json", "x-hub-signature-256": "sha256=..."},
    "query": {},
    "body_base64": "eyJhY3Rpb24iOiJvcGVuZWQifQ=="
}

connic entfernt das eigene Secret (X-Connic-Secret, einen passenden Authorization-Header und den Query-Parameter secret) sowie Header, die das eigene Netzwerk hinzufügt. Der unveränderte Body ist bis 1 MiB und nicht bei Multipart-Anfragen enthalten; sonst ist body_omitted true. Die Run-Details zeigen den Body sowie die Header Authorization, Proxy-Authorization, Cookie und X-API-Key als [REDACTED]. Anders gestartete Runs, etwa erneute Runs und Tests, haben keine Anfrage.

Eine HMAC-Signatur prüfen, etwa X-Hub-Signature-256 von GitHub:

import base64
import hashlib
import hmac
import os

from connic import StopProcessing


async def before(content, context):
    request = context.get("request")
    if request is None:  # Nicht durch eine Webhook-Anfrage gestartet, etwa ein erneuter Run
        return content
    body = base64.b64decode(request.get("body_base64") or "")
    digest = hmac.new(os.environ["GITHUB_WEBHOOK_SECRET"].encode(), body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(f"sha256={digest}", request["headers"].get("x-hub-signature-256", "")):
        raise StopProcessing("Invalid signature", publish_outbound=False)
    return content

Ein signiertes JWT prüfen, etwa das Bot-Framework-Token, das Microsoft Teams sendet. Teams kann das connic-Secret nicht als Header senden, daher ?secret= an die URL des Messaging-Endpunkts anhängen.

# requirements.txt: PyJWT[crypto]
import asyncio
import os

import jwt
from connic import StopProcessing

keys = jwt.PyJWKClient("https://login.botframework.com/v1/.well-known/keys")


async def before(content, context):
    request = context.get("request")
    if request is None:  # Nicht durch eine Webhook-Anfrage gestartet, etwa ein erneuter Run
        return content
    token = request["headers"].get("authorization", "").removeprefix("Bearer ")
    try:
        key = await asyncio.to_thread(keys.get_signing_key_from_jwt, token)
        claims = jwt.decode(
            token, key.key, algorithms=["RS256"], audience=os.environ["MICROSOFT_APP_ID"],
            issuer="https://api.botframework.com", leeway=300,
        )
    except jwt.PyJWTError:
        raise StopProcessing("Invalid token", publish_outbound=False)
    if claims.get("serviceUrl") != context["payload"].get("serviceUrl"):
        raise StopProcessing("Invalid token", publish_outbound=False)
    return content

Fehlerantworten

Einrichtung

1. 1

   Endpoint einrichten

   Erstelle auf dem Server einen Endpoint, der POST-Anfragen empfangen kann.

2. 2

   Verbindung erstellen

   Öffne den Agenten, klicke auf Add outbound connector, dann auf Create New Connector und wähle HTTP Webhook.

3. 3

   Konfigurieren und erstellen

   Wähle den Mode Outbound, gib die Ziel-URL ein, an die connic Ergebnisse per POST senden soll, wähle optional eine Bridge für den Zugriff auf ein privates Netzwerk und klicke auf Create. Ergebnisse verknüpfter Agenten werden mit Signatur-Headern per POST an die konfigurierte URL gesendet.

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

1. 1

   Verbindung erstellen

   Öffne den Agenten, klicke im Verbindungsflussdiagramm auf Add inbound connector, dann auf Create New Connector und wähle HTTP Webhook.

2. 2

   Sync (Request-Response) auswählen und Zugangsdaten kopieren

   Wähle den Mode und klicke auf Create. Der Detail-Drawer öffnet sich automatisch und zeigt unter Configuration die Webhook URL und das Secret. Um sie später anzuzeigen, bewege den Mauszeiger im Verbindungsflussdiagramm über die Verbindung und klicke auf das Augensymbol.

3. 3

   Anfragen senden

   Sende JSON per POST an die Webhook URL. Die HTTP-Anfrage bleibt bis zum Abschluss des Agenten offen und erhält das Ergebnis direkt als Antwort.

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

Schlägt der Agenten-Run fehl, enthält die Antwort status: "failed" und die Fehlermeldung; auch der Verbindungs-Run wird als fehlgeschlagen erfasst.

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. 1

   Öffne im Bereich Agenten die Detailseite des Agenten

2. 2

   Füge über den Button + im Verbindungsflussdiagramm eine Webhook-Verbindung hinzu oder wähle eine vorhandene aus

3. 3

   Klicke auf das Augensymbol der Verbindung, um ihre Details zu öffnen

4. 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"}'

Absender prüfen

Manche Absender signieren ihre Anfragen, etwa mit einem HMAC-Signatur-Header oder einem JWT in Authorization. Jeder Webhook-Run enthält die ursprüngliche Anfrage in context["request"], damit Middleware die Signatur prüfen kann, bevor der Agent läuft: Methode, Header mit kleingeschriebenen Namen, Query-Parameter und den unveränderten Body als body_base64.

# context["request"] in Middleware, Tools und Hooks
{
    "method": "POST",
    "headers": {"content-type": "application/json", "x-hub-signature-256": "sha256=..."},
    "query": {},
    "body_base64": "eyJhY3Rpb24iOiJvcGVuZWQifQ=="
}

connic entfernt das eigene Secret (X-Connic-Secret, einen passenden Authorization-Header und den Query-Parameter secret) sowie Header, die das eigene Netzwerk hinzufügt. Der unveränderte Body ist bis 1 MiB und nicht bei Multipart-Anfragen enthalten; sonst ist body_omitted true. Die Run-Details zeigen den Body sowie die Header Authorization, Proxy-Authorization, Cookie und X-API-Key als [REDACTED]. Anders gestartete Runs, etwa erneute Runs und Tests, haben keine Anfrage.

Eine HMAC-Signatur prüfen, etwa X-Hub-Signature-256 von GitHub:

import base64
import hashlib
import hmac
import os

from connic import StopProcessing


async def before(content, context):
    request = context.get("request")
    if request is None:  # Nicht durch eine Webhook-Anfrage gestartet, etwa ein erneuter Run
        return content
    body = base64.b64decode(request.get("body_base64") or "")
    digest = hmac.new(os.environ["GITHUB_WEBHOOK_SECRET"].encode(), body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(f"sha256={digest}", request["headers"].get("x-hub-signature-256", "")):
        raise StopProcessing("Invalid signature", publish_outbound=False)
    return content

Ein signiertes JWT prüfen, etwa das Bot-Framework-Token, das Microsoft Teams sendet. Teams kann das connic-Secret nicht als Header senden, daher ?secret= an die URL des Messaging-Endpunkts anhängen.

# requirements.txt: PyJWT[crypto]
import asyncio
import os

import jwt
from connic import StopProcessing

keys = jwt.PyJWKClient("https://login.botframework.com/v1/.well-known/keys")


async def before(content, context):
    request = context.get("request")
    if request is None:  # Nicht durch eine Webhook-Anfrage gestartet, etwa ein erneuter Run
        return content
    token = request["headers"].get("authorization", "").removeprefix("Bearer ")
    try:
        key = await asyncio.to_thread(keys.get_signing_key_from_jwt, token)
        claims = jwt.decode(
            token, key.key, algorithms=["RS256"], audience=os.environ["MICROSOFT_APP_ID"],
            issuer="https://api.botframework.com", leeway=300,
        )
    except jwt.PyJWTError:
        raise StopProcessing("Invalid token", publish_outbound=False)
    if claims.get("serviceUrl") != context["payload"].get("serviceUrl"):
        raise StopProcessing("Invalid token", publish_outbound=False)
    return content

Fehlerantworten