Webhooks und REST-API

Conviro bietet Webhooks für Event-Benachrichtigungen in Echtzeit und eine REST-API für den programmatischen Zugriff auf alle Funktionen der Plattform.

Webhooks

Was sind Webhooks?

Webhooks senden eine HTTP-POST-Anfrage an Ihren Server, sobald in Conviro ein bestimmtes Ereignis eintritt. So können Sie in Echtzeit reagieren, ohne pollen zu müssen.

Verfügbare Events

Event	Wird ausgelöst, wenn
`message.new`	Eine neue Nachricht gesendet wird (von Besucher oder Bot)
`session.started`	Eine neue Konversationssitzung beginnt
`session.closed`	Eine Konversation geschlossen wird
`session.escalated`	Eine Konversation eskaliert wird
`lead.captured`	Ein neuer Lead erfasst wird
`lead.created`	Ein Lead-Datensatz angelegt wird
`lead_form.submitted`	Ein Lead-Formular abgeschickt wird
`handoff.requested`	Eine Übergabe an einen menschlichen Agenten angefordert wird
`csat.submitted`	Eine CSAT-Bewertung abgegeben wird
`csat.received`	Ein CSAT-Ergebnis erfasst wird
`ai.failed`	Die KI keine Antwort erzeugen kann
`ticket.created`	Ein Support-Ticket eröffnet wird
`ticket.resolved`	Ein Support-Ticket gelöst wird
`contact.created`	Ein neuer Kontakt angelegt wird
`contact.updated`	Ein Kontakt aktualisiert wird
`contact.merged`	Zwei Kontakte zusammengeführt werden
`contact.deleted`	Ein Kontakt gelöscht wird

Das Webhook-Formular bietet zusätzlich Alle Events, was jedes der obigen Events abonniert (gespeichert als Wildcard *); ein einzelner Webhook akzeptiert auch eine kommagetrennte Liste von Event-Namen.

Einrichtung

Öffnen Sie Dashboard -> Entwickler -> Webhooks.
Klicken Sie auf Add Webhook.
Geben Sie die URL Ihres Endpunkts ein (muss HTTPS sein).
Wählen Sie die Events aus, die Sie empfangen möchten.
Klicken Sie auf Save.

Sicherheit: HMAC-SHA256-Signierung

Jede Webhook-Payload wird mit HMAC-SHA256 und Ihrem Webhook-Secret signiert. Prüfen Sie die Signatur auf Ihrem Server, um die Authentizität sicherzustellen:

X-Webhook-Signature: t=<unix_timestamp>,v1=<hex_digest>
X-Webhook-Event: <event_name>
X-Webhook-Retry: <attempt>          # only on a retried delivery

Der Digest wird über <unix_timestamp>.<roher_request_body> gebildet; wer nur den Body prüft, erhält nie eine Übereinstimmung. Teilen Sie den Header an ,, lesen Sie die Werte t= und v1=, berechnen Sie den HMAC-SHA256 von t + '.' + rawBody mit Ihrem Webhook-Secret neu und vergleichen Sie beide Digests in konstanter Zeit. Weisen Sie Zustellungen zurück, deren Zeitstempel älter als wenige Minuten ist, damit ein abgefangenes Payload nicht erneut eingespielt werden kann. Hinweis: Test senden an eine URL, die kein gespeicherter Webhook ist, wird unsigniert zugestellt — es gibt kein Secret zum Signieren; testen Sie Ihre Prüfung gegen einen gespeicherten Endpunkt.

Wiederholungsrichtlinie

Gibt Ihr Endpunkt einen Statuscode außerhalb von 2xx zurück, versucht Conviro es bis zu 3-mal erneut – mit exponentiellem Backoff (1 Min., 5 Min., 30 Min.).

REST-API

Authentifizierung

Erstellen Sie unter Dashboard -> Entwickler -> API-Schlüssel -> API-Schlüssel erstellen einen API-Schlüssel.
Übergeben Sie ihn im Authorization-Header:

Authorization: Bearer sk_your_api_key_here

> Der Schlüssel wird nur einmal angezeigt. Für die Erstellung ist mindestens ein Scope erforderlich — Erstellen bleibt deaktiviert, bis Sie einen wählen — und der vollständige sk_-Wert erscheint genau einmal, in einem Dialog, der sich bewusst nicht per Escape oder Klick auf den Hintergrund schließen lässt. Danach bleibt nur das Präfix lesbar; der Rest ist ein bcrypt-Hash und nicht wiederherstellbar. Kopieren Sie ihn, bevor Sie den Dialog schließen. Bei Verlust erstellen Sie einen neuen Schlüssel und widerrufen den alten.

Wichtige Endpunkte

Methode	Endpunkt	Beschreibung
GET	`/api/chatbots`	Alle Chatbots auflisten
GET	`/api/chatbots/:id`	Details eines Chatbots abrufen
GET	`/api/sessions`	Sitzungen auflisten (mit Filtern)
GET	`/api/sessions/:id/messages`	Nachrichten einer Sitzung abrufen
POST	`/api/sessions/:id/messages`	Eine Nachricht an eine Sitzung senden
GET	`/api/contacts`	Kontakte auflisten
POST	`/api/contacts`	Einen Kontakt anlegen
GET	`/api/leads`	Leads auflisten
POST	`/api/leads`	Einen Lead anlegen
GET	`/api/analytics/overview`	Analytics-Zusammenfassung abrufen

Rate Limits

Free-Tarif: 60 Anfragen/Minute
Starter: 120 Anfragen/Minute
Pro: 300 Anfragen/Minute
Growth+: 600 Anfragen/Minute

Die Rate-Limit-Header sind in jeder Antwort enthalten:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1672531200

Vollständige Dokumentation

Unter /developers finden Sie die komplette API-Referenz mit Beispielen für Requests und Responses.