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.handoff`	Eine Konversation an einen menschlichen Agenten übergeben wird
`lead.captured`	Ein neuer Lead erfasst wird
`contact.created`	Ein neuer Kontakt angelegt wird
`ticket.created`	Ein Support-Ticket eröffnet wird
`csat.submitted`	Eine CSAT-Bewertung abgegeben wird

Einrichtung

Öffnen Sie Dashboard -> Settings -> 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-Conviro-Signature: sha256=<hex_digest>

Vergleichen Sie diesen Header mit dem HMAC-SHA256-Digest des rohen Request-Bodys, den Sie mit Ihrem Webhook-Secret berechnen.

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 -> Settings -> API Keys -> Create Key einen API-Schlüssel.
Übergeben Sie ihn im Authorization-Header:

Authorization: Bearer sk_your_api_key_here

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.