receptionworksHilfe

Integrationen und Webhooks

Senden Sie Unterhaltungen, Buchungen, Teamanforderungen und Supportanfragen an Zapier, Make oder Ihren Server; prüfen Sie Signatur und Zustellung.

Integrationen senden Ereignisse Ihres Unternehmens sofort an einen anderen Dienst: eine neue Unterhaltung, eine Buchung, die Anforderung eines Teammitglieds, eine Supportanfrage. Mit Zapier oder Make können Sie zum Beispiel eine Zeile in einer Tabelle ergänzen, eine Chatnachricht senden oder einen CRM-Eintrag anlegen, ohne Daten von Hand zu kopieren.

Wo Sie die Integrationen finden

Öffnen Sie im Hauptmenü „Module“, verbinden Sie das Modul „Integrationen“ (es ist standardmäßig ausgeschaltet) und klicken Sie auf seiner Karte auf „Integrationen öffnen“. Der Tab „Webhooks“ wird geöffnet, daneben liegt der Tab „Ereignisprotokoll“. Den Bereich öffnen nur Inhaber und Administrator: Die Adresse eines Empfängers kann ein privates Token enthalten. Solange das Modul ausgeschaltet ist, wird nichts zugestellt, und Ereignisse in dieser Zeit werden später nicht nachgesendet. Die Empfänger bleiben eingerichtet, das Ereignisprotokoll wird weiter geführt.

Empfänger hinzufügen

  1. Erstellen Sie in Zapier einen Zap mit dem Trigger „Webhooks by Zapier“ und dem Ereignis „Catch Hook“ und kopieren Sie die angezeigte Adresse. In Make fügen Sie das Modul „Custom webhook“ hinzu und kopieren dessen Adresse.
  2. Füllen Sie auf der Seite „Integrationen“ die Felder „Name“ (zum Beispiel der Name des Zaps) und „Adresse des Empfängers“ (die kopierte Adresse) aus.
  3. Markieren Sie unter „Zu sendende Ereignisse“, was gesendet werden soll.
  4. Klicken Sie auf „Empfänger hinzufügen“.
  5. Das Signaturgeheimnis erscheint nur einmal. Kopieren Sie es und bewahren Sie es sicher auf. Zapier und Make brauchen es nicht; Ihr eigener Server prüft damit die Signatur. Bei Verlust erstellen Sie über „Geheimnis ändern“ ein neues.
  6. Klicken Sie auf der Karte des Empfängers auf „Test senden“. Das Ergebnis lautet Zugestellt oder Nicht zugestellt mit Grund.

Die Adresse muss öffentlich sein und mit https beginnen. Abgelehnt werden, mit Nennung des Grundes: http-Adressen, IP-Adressen statt einer Domain, eigene Ports, Adressen mit Benutzername und Passwort, interne Adressen und Adressen auf ReceptionWorks-Domains. Die Seite zeigt nur Host und Pfad der Adresse: Der Teil nach dem Fragezeichen kann das Token Ihres Empfängers enthalten.

Welche Ereignisse gesendet werden

Ereignisse aus dem Testchat werden nicht gesendet. Ein Empfänger bekommt nur Ereignisse, die nach seinem Hinzufügen und bei aktiver Schaltung eintreten: Was während einer Pause oder Deaktivierung geschah, wird nicht nachgesendet.

„Neue Nachricht“ und „Gesamte Unterhaltung“ enthalten den vollständigen Text der Unterhaltungen, auch das, was Kunden schreiben. Der Text verlässt ReceptionWorks und geht an den von Ihnen gewählten Empfänger. Haken Sie sie daher nur für Empfänger an, denen Sie vertrauen. Ein neuer Empfänger startet ohne diese beiden Haken. Sie werden nur gesendet, solange ein Empfänger sie angehakt hat, und erscheinen weder im Ereignisprotokoll noch in dessen Export: Die Unterhaltung selbst steht im Posteingang. Testchats und gesperrte Kunden werden nicht gesendet.

Was der Empfänger erhält

Jedes Ereignis ist eine POST-Anfrage mit JSON-Inhalt. Beispiel für die Anforderung eines Teammitglieds durch einen KI-Mitarbeiter:

{
  "schema_version": "business-webhook.v1",
  "id": "5b0c5e2e-0000-4000-8000-000000000001",
  "type": "conversation.handoff_requested",
  "occurred_at": "2026-10-07T09:30:00.000Z",
  "business": { "name": "Example Studio" },
  "actor": { "kind": "ai_employee" },
  "channel": "telegram",
  "employee": { "name": "Anna" },
  "conversation": { "url": "https://app.example.com/businesses/studio/inbox?conversation=example" },
  "customer": { "name": "Maria", "email": "maria@example.com", "phone": "+1 555 0100" },
  "booking": null,
  "handoff": { "reason": "ai_request", "reason_text": "The customer wants to discuss a discount" },
  "support_case": null
}

Abschnitte, die nicht zum Ereignis passen, sind null. Das Ereignis von „Test senden“ hat den Typ webhook.test, alle Abschnitte außer business sind null. Die Daten enthalten keinen übersetzten Text: Namen sind wie gespeichert, Codes sind feste englische Wörter und Zeiten sind in UTC.

"message": {
  "id": "6c1d0f52-0000-4000-8000-000000000002",
  "sequence": 12,
  "author": "customer",
  "text": "Hello, can I book for Friday?",
  "created_at": "2026-10-07T09:29:41.000Z",
  "attachments": [{ "kind": "image", "name": "photo.jpg", "media_type": "image/jpeg" }]
}

Nachrichten und Transkripte können in falscher Reihenfolge eintreffen und sich wiederholen: Verlassen Sie sich nicht auf die Ankunftsreihenfolge. Stellen Sie mit sequence die Reihenfolge der Nachrichten einer Unterhaltung wieder her und verwerfen Sie Zustellungen, deren webhook-id Sie schon verarbeitet haben. Das Transkript wiederholt Nachrichten, die Sie vielleicht schon einzeln erhalten haben: Nutzen Sie es, um die ganze Unterhaltung zu prüfen oder neu aufzubauen.

Signatur prüfen

Jede Anfrage trägt drei Header des Standards Standard Webhooks: webhook-id, webhook-timestamp und webhook-signature. Zapier und Make prüfen sie nicht. Auf Ihrem eigenen Server nutzen Sie die offizielle Standard- Webhooks-Bibliothek für Ihre Sprache: Übergeben Sie ihr das Geheimnis genau wie angezeigt (es beginnt mit whsec_), den unveränderten Rohinhalt der Anfrage und die drei Header. Manuelle Prüfung:

signed_content = webhook-id + "." + webhook-timestamp + "." + raw request body
signature      = "v1," + base64( HMAC-SHA256( key, signed_content ) )
key            = base64-decoded part of the secret after "whsec_"

Der Header webhook-signature enthält v1, und die Signatur. Nach „Geheimnis ändern“ enthält er zwei Signaturen, durch ein Leerzeichen getrennt: Akzeptieren Sie die Anfrage, wenn eine davon passt. Lehnen Sie Anfragen ab, deren Zeitstempel mehr als fünf Minuten von Ihrer Uhr abweicht.

Wiederholungen und automatische Abschaltung

Der Empfänger muss innerhalb von 10 Sekunden mit einem 2xx-Code antworten. Weiterleitungen werden nicht verfolgt: Eine Adresse, die weiterleitet, gilt als Fehler. Sonst versucht ReceptionWorks es erneut: sofort, dann nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden und 12 Stunden. Das sind 7 Versuche in etwa 21 Stunden. Schlagen alle fehl, steht die Zustellung in „Zustellprotokoll“ als Nicht zugestellt, und Sie können „Erneut senden“ klicken. Wiederholungen tragen dieselbe webhook-id, sodass der Empfänger Duplikate verwerfen kann.

Ein Empfänger wird automatisch deaktiviert, wenn er meldet, dass die Adresse nicht mehr existiert (Code 410), oder wenn fünf Ereignisse in Folge nicht zugestellt wurden. Die Karte zeigt dann „Automatisch deaktiviert“ mit dem Grund, und Ihr Team erhält eine Benachrichtigung. Korrigieren Sie die Adresse und klicken Sie auf „Aktivieren“: Verpasste Ereignisse werden nicht nachgesendet.

Pause, neues Geheimnis, Löschen

Gut zu wissen

Wie es weitergeht

← Alle Artikel