AnmeldenKostenlos testen

Webhook-Integrationen

Aktualisiert am 20.10.20264 Min. Lesezeit
Deutsch
Auf dieser Seite

Webhooks schicken Ereignisse aus Deskwoot in Echtzeit an deinen eigenen Endpunkt. Konversation erstellt, Nachricht erstellt, Kontakt aktualisiert: Du wählst die Ereignisse aus, gibst eine URL an, und Deskwoot sendet per POST JSON an diese URL, sobald ein Ereignis passiert. Jede Zustellung ist per HMAC signiert, so kannst du prüfen, ob sie wirklich von Deskwoot kommt. Praktisch, um ein CRM zu synchronisieren, eigene Abläufe zu starten oder Ereignisse in dein Data Warehouse zu schreiben.

Webhook-Integrationen

Webhooks in Deskwoot sind HTTP-Callbacks, die ausgelöst werden, wenn in deiner Inbox etwas passiert (neue Konversation, neue Nachricht, Statusänderung). So kannst du Supportereignisse mit einem CRM synchronisieren, eine externe Automatisierung starten oder sie in deiner eigenen Datenbank protokollieren, ohne die API ständig abzufragen. Webhooks sind ein schlanker, ereignisgesteuerter Weg, alles synchron zu halten.

Diese Anleitung zeigt dir, wie du einen Webhook erstellst, die passenden Ereignisse wählst und häufige Probleme löst.

Einen Webhook erstellen

  1. Gehe in deinem Deskwoot-Dashboard zu Einstellungen > Webhooks.
  2. Klicke auf Webhook hinzufügen.
  3. Gib unter Endpunkt-URL die Adresse ein, die die Ereignisdaten empfangen soll. Die URL muss öffentlich erreichbar sein und mit HTTPS beginnen.
  4. Wähle unter Ereignisse abonnieren die Ereignisse aus, die du empfangen willst (zum Beispiel Konversation erstellt, Nachricht erstellt oder Kontakt aktualisiert). Wählst du keines aus, werden alle Ereignisse gesendet.
  5. Klicke auf Webhook erstellen, um den Webhook zu aktivieren.

Danach sendet Deskwoot bei jedem passenden Ereignis eine HTTP-POST-Anfrage mit einem JSON-Payload an deine URL.

Tipps aus der Praxis

  • Nutze nur HTTPS-Endpunkte. So sind die Ereignisdaten bei der Übertragung verschlüsselt, und sensible Kundendaten bleiben geschützt.
  • Abonniere gezielt. Wähle nur die Ereignisse, die du wirklich brauchst. Alle Ereignisse zu abonnieren erzeugt viele Anfragen und erschwert die Fehlersuche.
  • Antworte schnell. Dein Endpunkt sollte so schnell wie möglich einen 2xx-Statuscode zurückgeben. Verlagere aufwendige Verarbeitung in einen Hintergrundjob, um Timeouts zu vermeiden.
  • Protokolliere eingehende Payloads. Speichere bei der ersten Einrichtung das rohe JSON, damit du die Struktur prüfen und deine Integration sauber aufbauen kannst.
  • Mach deinen Endpunkt idempotent. In seltenen Fällen kommt ein Ereignis mehr als einmal an. Baue deinen Handler so, dass ein doppelt verarbeitetes Ereignis keine doppelten Aktionen auslöst.

Fehlerbehebung

  • Keine Ereignisse? Prüfe, ob deine Endpunkt-URL stimmt, öffentlich erreichbar ist und mit 2xx antwortet. Firewalls oder IP-Freigabelisten können eingehende Anfragen unbemerkt blockieren.
  • Unerwartetes Payload-Format? Stelle sicher, dass du den Body als JSON parst (Content-Type: application/json). Prüfe deine Serverprotokolle auf Parsing-Fehler.
  • Ereignisse kommen verspätet an? Bei hohem Datenaufkommen kann es kurze Verzögerungen geben. Wenn sie anhalten, prüfe, ob dein Server eingehende Verbindungen drosselt oder in eine Warteschlange stellt.

Häufige Fragen

Welche Ereignisse kann ich abonnieren?
Konversation erstellt, Konversation aktualisiert, Konversation zugewiesen, Konversation gelöst, Nachricht erstellt, Kontakt erstellt, Kontakt aktualisiert und CSAT abgegeben. Wählst du kein Ereignis aus, bekommt der Webhook alle. Jedes Ereignis hat eigene Daten im Payload, Details stehen in der API-Dokumentation.
Ist die Zustellung signiert?
Ja. Jede Anfrage hat einen Header X-Deskwoot-Signature (sha256= und dahinter der Hex-HMAC-SHA256 des rohen Bodys, signiert mit dem Secret deines Webhooks) und einen Header X-Deskwoot-Event mit dem Namen des Ereignisses. Das Dashboard zeigt das Secret nicht an; wenn du den Webhook über die REST-API erstellst, bekommst du es einmal in der Antwort. Prüfe die Signatur vor der Verarbeitung, das schützt vor gefälschten Anfragen.
Wiederholt Deskwoot fehlgeschlagene Zustellungen?
Einmal. Antwortet dein Endpunkt nicht mit 2xx oder nicht innerhalb von 10 Sekunden, versucht Deskwoot es nach 5 Sekunden noch einmal. Schlägt auch das fehl, wird das Ereignis verworfen. Baue deinen Endpunkt deshalb idempotent und robust gegen kurze Ausfälle.
Wie schnell kommen Webhooks an?
Deskwoot sendet jedes Ereignis sofort, wenn es passiert, ohne Warteschlange. Dein Endpunkt hat 10 Sekunden Zeit für die Antwort. Dauert es länger, gilt die Zustellung als fehlgeschlagen und wird einmal wiederholt.
Brauche ich HTTPS?
Ja. Deskwoot sendet nur an öffentliche HTTPS-URLs, eine HTTP-URL wird beim Anlegen abgelehnt. Das ist wichtig, weil die Payloads Kundendaten enthalten.
Wie sieht die Anfrage aus?
POST mit Content-Type: application/json. Der Body ist ein JSON-Objekt mit event, data (die Daten des Ereignisses), timestamp und accountId. Die Daten jedes Ereignisses beschreibt die API-Dokumentation.
Kann ich doppelte Ereignisse bekommen?
Selten, aber möglich, etwa wenn die Wiederholung startet, obwohl dein Endpunkt die erste Anfrage schon verarbeitet hat. Der Body enthält keine Ereignis-ID. Nutze den Namen des Ereignisses zusammen mit der ID des Objekts in data (zum Beispiel der Nachricht), um bereits verarbeitete Ereignisse zu überspringen.
Kann ich Ereignisse vor dem Versand filtern?
Nach Ereignistyp ja, über die Auswahl beim Abonnieren. Nach Inhalt (etwa „nur Konversationen aus Inbox X“) nicht. Abonniere das Ereignis und filtere auf deinem Endpunkt.
Was passiert, wenn mein Endpunkt einige Stunden nicht erreichbar ist?
Ereignisse aus dieser Zeit gehen verloren, denn Deskwoot speichert sie über die eine Wiederholung hinaus nicht. Überwache deshalb die Verfügbarkeit deines Endpunkts. Nach dem Ausfall kannst du über die REST-API (Enterprise) Konversationen nach der neuesten Aktivität abrufen und deinen Stand abgleichen.
Kann ich mehrere Webhooks für verschiedene Endpunkte einrichten?
Ja. Erstelle mehrere Webhooks, jeden mit eigener URL und eigenen Ereignissen. Praktisch, wenn ein Tool alle Ereignisse braucht und ein anderes nur einige.
Wie teste ich einen Webhook vor dem Livegang?
Nutze bei der Einrichtung einen Dienst mit temporärer URL wie webhook.site oder RequestBin. Sieh dir die echten Payloads an, prüfe deinen Parser und stelle dann auf deinen Produktiv-Endpunkt um.

War diese Anleitung hilfreich?

Weiterlesen

Fynn zu dieser Anleitung fragen

Kurze Antwort aus dieser Anleitung und dem restlichen Hilfecenter.

Noch Hilfe nötig?

Fynn antwortet im Chat aus diesen Anleitungen, und dort erreichst du auch das Team.

E-Mail schreiben