Zum Hauptinhalt springen
connic

HTTP-Webhooks

Von connic
InboundOutboundSync

Wenn ein System eine HTTP-Anfrage senden kann, kann es einen Agenten starten. Sende JSON, Formulardaten oder Dateien, und du bekommst die Run-IDs oder die Antwort des Agenten zurück.

Zu einem Agenten hinzufügenSprich mit Sales
Publisher
Von connic
Modi
Inbound, Outbound, Sync
Einrichtung
Dashboard oder connectors/*.yaml
Dokumentation
HTTP-Webhooks Docs

Lege fest, was der Aufrufer zurückbekommt

Ein Verbindungstyp deckt Events ohne Antwort, Request und Response sowie die Zustellung von Ergebnissen ab.

Inbound
connic antwortet sofort mit den Run-IDs und startet jeden verknüpften Agenten im Hintergrund.
Sync
Die Anfrage bleibt offen, bis der Agent fertig ist, und die Response enthält seine Ausgabe. Das Standard-Timeout beträgt fünf Minuten.
Outbound
connic sendet das Ergebnis per POST an deine URL, wenn ein Run abgeschlossen ist oder wenn der Agent oder seine Middleware es während des Runs sendet.
request.sh
curl -X POST <webhook-url> \
  -H "Content-Type: application/json" \
  -H "X-Connic-Secret: <your-secret-key>" \
  -d '{"order_id": "ord_8812", "question": "Where is my order?"}'
inbound-response.json
{
  "status": "ok",
  "dispatched_to": 1,
  "run_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}
sync-response.json
{
  "status": "ok",
  "result": {
    "run_id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_name": "order-assistant",
    "status": "completed",
    "output": "Order ord_8812 shipped on October 12.",
    "error": null
  }
}

Sende JSON, Formularfelder oder Dateien

Der Request Body wird zur Eingabe des Agenten, und hochgeladene Dateien gehen zusammen damit an das Modell.

JSON und Formulardaten
Ein JSON Body kommt unverändert an, Formularfelder werden zu Key-Value-Paaren, und ein GET übergibt seine Query-Parameter ohne das Secret.
Datei-Uploads
Sende multipart/form-data mit bis zu 10 Dateien und insgesamt 10 MiB. Die Verbindung nimmt Bilder, PDFs, Office-Dokumente und Datendateien an, und das Modell liest die Formate, die es unterstützt.
Pflichtdateien
Aktiviere Files required an der Agent-Verknüpfung, dann schlägt eine Anfrage ohne Datei fehl, bevor der Run startet.
upload.sh
curl -X POST <webhook-url> \
  -H "X-Connic-Secret: <your-secret-key>" \
  -F "instructions=What is the total of this invoice?" \
  -F "file=@invoice.pdf"
context["payload"]
{
  "instructions": "What is the total of this invoice?",
  "files": [
    {
      "name": "invoice.pdf",
      "field_name": "file",
      "mime_type": "application/pdf",
      "data": "<base64-bytes>",
      "size": 48213
    }
  ]
}

Halte den Webhook neben deinen Agenten

Deklariere ihn als YAML-Datei in connectors/. Jedes Deployment legt ihn für sein Environment an oder aktualisiert ihn, und ein Rollback stellt ihn wieder her. URL und Secret erzeugt connic, deshalb stehen beide nicht in der Datei.

connectors/order-questions.yaml
type: webhook
mode: sync
name: Order questions
agents:
  - order-assistant
create: connectors/order-questions.yaml (http)

Jede Anfrage geprüft, jede Zustellung signiert

Inbound- und Sync-Webhooks verlangen standardmäßig das Secret der Verbindung, und jede ausgehende Zustellung trägt eine Signatur, die dein Endpoint prüfen kann.

Ein Secret bei jedem Aufruf
Sende es als X-Connic-Secret, als Bearer Token oder als Query-Parameter secret. Bei falschem Secret antwortet connic mit 401, und kein Run startet.
Signierte Zustellungen
X-Connic-Signature enthält einen HMAC-SHA256 über Timestamp und unveränderten Body. Lehne Zustellungen ab, deren X-Connic-Timestamp älter als fünf Minuten ist.
Private Endpoints
Leite ausgehende Zustellungen über eine Bridge, wenn der Endpoint in deinem Netzwerk liegt.
verify_webhook.py
import hashlib
import hmac
import time


def verify_webhook(
    body: bytes, signature: str, timestamp: str, secret: str
) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    signed = f"{timestamp}.".encode() + body
    expected = hmac.new(
        secret.encode(), signed, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Wo ein Webhook passt

Wähle ein Szenario und sieh, woher die Anfrage kommt, was sie sendet und wohin das Ergebnis geht.

Dein Shop-Backend fragt nach einer Bestellung und zeigt die Antwort aus derselben Response an.

Shop-Backend
Sync Webhook
order-assistant
Antwort in der Response
order-question.json
{
  "order_id": "ord_8812",
  "question": "Where is my order?"
}
response.json
{
  "status": "ok",
  "result": {
    "run_id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_name": "order-assistant",
    "status": "completed",
    "output": "Order ord_8812 shipped on October 12.",
    "error": null
  }
}

Die Buchhaltungssoftware lädt jedes PDF hoch und bekommt Positionen und geprüfte Summen zurück.

Buchhaltungssoftware
Sync Webhook
invoice-pipeline
Positionen und Summen
upload.sh
curl -X POST <webhook-url> \
  -H "X-Connic-Secret: <your-secret-key>" \
  -F "file=@invoice-2041.pdf"
result.output
{
  "valid": true,
  "checks": {
    "tax_matches_rate": true,
    "total_matches_calculation": true,
    "line_total_consistent": true
  },
  "message": "All totals verified"
}

Das Helpdesk sendet jedes neue Ticket, und ein ausgehender Webhook schickt den Antwortentwurf zurück, sobald der Run fertig ist.

Helpdesk
Inbound Webhook
support-triage
Antwortentwurf an die Helpdesk-API
new-ticket.json
{
  "ticket_id": "T-4821",
  "priority": "urgent",
  "subject": "Card charged twice",
  "body": "I was billed twice for my October order."
}
outbound-payload.json
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "support-triage",
  "status": "completed",
  "output": "Sorry for the double charge. We will refund the second payment.",
  "error": null,
  "started_at": "2026-10-13T09:00:00Z",
  "ended_at": "2026-10-13T09:00:06Z",
  "token_usage": {
    "input_tokens": 812,
    "output_tokens": 64,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 876
  }
}

Dein Formular-Tool sendet jede Anmeldung, und ein ausgehender Webhook schreibt die Recherche in dein CRM.

Anmeldeformular
Inbound Webhook
lead-researcher
Recherche im CRM
signup.json
{
  "email": "jana@example.com",
  "company": "Example GmbH",
  "plan_interest": "Pro"
}
outbound-payload.json
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_name": "lead-researcher",
  "status": "completed",
  "output": "Example GmbH: logistics software, 40 people, fits the pro plan.",
  "error": null,
  "started_at": "2026-10-13T09:00:00Z",
  "ended_at": "2026-10-13T09:00:06Z",
  "token_usage": {
    "input_tokens": 812,
    "output_tokens": 64,
    "thinking_tokens": 0,
    "cached_input_tokens": 0,
    "total_tokens": 876
  }
}

FAQ zu HTTP-Webhooks

Füge dem Agenten eine HTTP-Webhook-Verbindung hinzu, kopiere URL und Secret und sende eine Anfrage. JSON Bodies, Formulardaten, Datei-Uploads und GET-Query-Parameter funktionieren. Im Modus Inbound antwortet connic mit den Run-IDs, während der Agent im Hintergrund arbeitet. Im Modus Sync kommt die Antwort des Agenten in derselben Response zurück. Weitere Möglichkeiten zeigen die gängigen Verbindungsmuster.

Inbound- und Sync-Webhooks prüfen das Secret der Verbindung, gesendet als X-Connic-Secret, als Authorization: Bearer Header oder als Query-Parameter secret. Ausgehende Zustellungen sind mit HMAC-SHA256 in X-Connic-Signature signiert und tragen X-Connic-Timestamp, damit dein Endpoint sie prüfen und Replays ablehnen kann.

Ja. Sende multipart/form-data mit einem oder mehreren Dateifeldern, bis zu 10 Dateien und insgesamt 10 MiB. Jede angenommene Datei geht zusammen mit der Eingabe an das Modell, und Middleware sieht die Dateien base64-codiert unter dem Key files der Payload.

Standardmäßig fünf Minuten. Für längere Aufgaben nutzt du den Modus Inbound, der sofort mit den Run-IDs antwortet, und lässt eine ausgehende Verbindung das Ergebnis zustellen, sobald der Run fertig ist.

Weitere Verbindungen

Zum Marketplace