Ausgehende Webhooks

Auf dieser Seite richten Sie Webhook-Ziele ein, an die 5sDesk bei Ereignissen (neues Ticket, geänderter Kunde, verschobene Karte) automatisch eine signierte Anfrage schickt. Die Seite sehen nur Admins.

Wo Sie die Seite finden

Verwaltung › Einstellungen › Boards & KI › “Ausgehende Webhooks”.

Einstellungen im Überblick

Der Hinweis am Seitenanfang: “5sDesk schickt bei jedem abonnierten Ereignis eine signierte POST-Anfrage an Ihr Ziel. Schlägt die Zustellung fehl, wird sie mehrfach wiederholt (1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 12 Stunden).”

Liste “Ziele”

Je Organisation sind höchstens 10 Ziele möglich. Ist die Grenze erreicht, ersetzt “Maximal 10 Ziele je Organisation erreicht.” den Button “Neues Ziel”.

Jeder Eintrag zeigt die Ziel-URL, die Beschreibung, die abonnierten Ereignisse (oder “Alle Ereignisse”), “Secret:” mit Anfang und letzten vier Zeichen des Secrets, “Zuletzt erfolgreich:”, “Zuletzt fehlgeschlagen:” und den Status “Aktiv” oder “Aus”.

Aktion	Wirkung
“Zustellungen”	Öffnet die Seite “Letzte Zustellungen” (siehe unten).
“Bearbeiten”	Öffnet “Webhook-Ziel bearbeiten”. Eine geänderte URL setzt die Fehlerzählung zurück.
“Testen”	Schickt sofort ein Ereignis vom Typ ping und meldet “Test erfolgreich: HTTP 200 in 123 ms.” oder “Test fehlgeschlagen: …”. Der Test wird nicht wiederholt und erscheint nicht in den Zustellungen.
“Ausschalten” / “Einschalten”	Schaltet das Ziel ab oder wieder an (“Ziel ausgeschaltet.”, “Ziel eingeschaltet.”). Einschalten setzt die Fehlerzählung zurück.
“Secret erneuern”	Erzeugt ein neues Secret und zeigt es einmalig an.
“Löschen”	Entfernt das Ziel samt Zustellungen sofort (“Ziel gelöscht.”).

Formular “Neues Webhook-Ziel” und “Webhook-Ziel bearbeiten”

Feld	Bedeutung	Standard
“Ziel-URL”	Adresse, an die 5sDesk sendet. “Nur https. Interne Adressen und localhost sind nicht erlaubt.” Höchstens 2048 Zeichen, keine Zugangsdaten in der URL.	leer
“Beschreibung (optional)”	Freitext zur Wiedererkennung, höchstens 200 Zeichen.	leer
“Ereignisse”	Checkboxen je Ereignis, gruppiert nach Bereich. “Ohne Auswahl werden alle Ereignisse geschickt.”	keine Auswahl (alle)
Checkbox “Mir ist bewusst, dass dabei personenbezogene Daten (unter anderem Name und E-Mail-Adresse von Kunden sowie Nachrichtentexte) an dieses Ziel übertragen werden, und dass dafür eine Rechtsgrundlage bestehen muss.”	Pflicht bei jedem Speichern, auch beim Bearbeiten. Ohne Haken: “Bitte bestätigen Sie die Datenübertragung.”.	nicht gesetzt

Ereignisse je Gruppe:

Gruppe	Ereignisse
“Tickets”	ticket.created, ticket.updated
“Nachrichten & Notizen”	message.created, note.created
“Kunden & Firmen”	customer.created, customer.updated, customer.deleted, company.created, company.updated, company.deleted
“Karten & Deals”	card.created, card.updated, card.moved, card.archived, card.unarchived

Abgelehnte Adressen melden zum Beispiel “Nur https-Adressen sind erlaubt.”, “Interne Adressen und localhost sind als Ziel nicht erlaubt.”, “Benutzername und Passwort in der URL sind nicht erlaubt.” oder “Der Host der URL ist nicht auflösbar.”.

Secret

Nach dem Anlegen erscheint der Block “Ziel angelegt”: “Das Secret wird nur dieses eine Mal angezeigt. Damit prüfen Sie die Signatur im Header X-5sDesk-Signature.” Mit “Kopieren” übernehmen Sie es in Ihr System.

Nach “Secret erneuern” erscheint “Neues Secret erzeugt”: “Das bisherige Secret bleibt 24 Stunden gültig – so lange werden beide Signaturen mitgeschickt und Sie können in Ruhe umstellen.”

Seite “Letzte Zustellungen”

Zeigt die letzten 50 Zustellungen an dieses Ziel. “Erfolgreiche Zustellungen werden 7 Tage aufbewahrt, endgültig fehlgeschlagene 30 Tage.”

Spalte	Inhalt
“Ereignis”	Ereignistyp und Zeitpunkt, bei manuell wiederholten Zustellungen der Vermerk “Erneut gesendet”.
“Status”	“Wartet”, “Läuft”, “Fehlgeschlagen”, “Zugestellt” oder “Aufgegeben”, dazu der HTTP-Status und die letzte Fehlermeldung.
“Versuche”	Anzahl der Versuche, bei “Fehlgeschlagen” zusätzlich “Nächster Versuch:”.
“Letzter Versuch”	Zeitpunkt und Dauer in Millisekunden.

“Inhalt anzeigen” klappt die gesendeten Daten auf. “Erneut senden” legt eine neue Zustellung mit genau demselben Inhalt an (“Zustellung erneut eingereiht.”). Das geht auch bei bereits zugestellten oder aufgegebenen Einträgen.

So gehen Sie vor

1. Klicken Sie auf “Neues Ziel”.
2. Tragen Sie die “Ziel-URL” Ihres Empfängers ein (https).
3. Wählen Sie unter “Ereignisse” nur die Typen, die Ihr System verarbeitet. Ohne Auswahl bekommt es alles.
4. Setzen Sie die Bestätigung zur Datenübertragung und klicken Sie auf “Speichern”.
5. Kopieren Sie das angezeigte Secret in Ihr System und prüfen Sie damit die Signatur jeder Anfrage.
6. Klicken Sie in der Liste auf “Testen”. Ihr System sollte das Ereignis ping empfangen und mit einem Erfolgsstatus antworten.

Auswirkungen

• Jedes abonnierte Ereignis erzeugt je aktivem Ziel eine Zustellung. 5sDesk prüft etwa alle 15 Sekunden auf fällige Zustellungen; eine Anfrage darf höchstens 10 Sekunden dauern, sonst gilt sie als fehlgeschlagen.
• Schlägt eine Zustellung fehl, wiederholt 5sDesk sie bis zu fünfmal mit wachsendem Abstand (1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 12 Stunden, jeweils leicht gestreut). Danach steht sie auf “Aufgegeben”.
• Wiederholungen schicken exakt denselben Inhalt wie der erste Versuch. Ihr System sollte Ereignisse anhand der mitgelieferten Ereignis-ID erkennen, denn eine Zustellung kann mehrfach ankommen und die Reihenfolge ist nicht garantiert.
• Massenvorgänge lösen keine Webhooks aus: Import aus Freshdesk oder Postfächern, der CSV-Import von Kunden und Firmen samt “Rückgängig machen”, Demo-Daten, das Zurücksetzen der Organisation und das Duplizieren eines Boards.
• Anders die Tag-Sammelaktion in der Kunden- und Firmenliste (“Tags hinzufügen” oder “Tags entfernen”): Sie löst für jeden Datensatz, dessen Tags sich tatsächlich geändert haben, ein eigenes customer.updated beziehungsweise company.updated aus. Bei vielen Datensätzen kommen entsprechend viele Ereignisse an.
• Beim Zusammenführen doppelter Kunden entstehen customer.deleted für die aufgelöste Dublette und customer.updated für den behaltenen Kunden.
• Weitere E-Mail-Adressen eines Kunden (“Hinzufügen”, “Adresse entfernen”, “Als Hauptadresse setzen”) lösen jeweils customer.updated aus.

Hinweise

Achtung

Ein Ziel schaltet sich selbst ab, wenn 20 Zustellungen in Folge fehlschlagen oder das Ziel mit 410 Gone antwortet. In der Liste steht dann “Automatisch abgeschaltet: 20 Zustellungen in Folge sind fehlgeschlagen.” beziehungsweise “Automatisch abgeschaltet: das Ziel hat mit 410 Gone geantwortet.”, noch offene Zustellungen werden verworfen, und alle Admins erhalten die Mail “Webhook-Endpunkt automatisch abgeschaltet”. Sobald das Ziel wieder erreichbar ist, klicken Sie auf “Einschalten”.

Achtung

“Löschen” fragt nicht nach und entfernt das Ziel mit allen Zustellungen sofort. Möchten Sie ein Ziel nur vorübergehend stilllegen, nutzen Sie “Ausschalten”.

Hinweis

Das Secret wird verschlüsselt gespeichert und nach dem Anlegen nicht mehr angezeigt. Ist es verloren, erzeugen Sie mit “Secret erneuern” ein neues; das alte bleibt 24 Stunden parallel gültig.

Siehe auch

• API & Integrationen: API-Schlüssel, mit denen Ihr System Details zu einem gemeldeten Ereignis nachladen kann; die Berechtigung webhooks:manage erlaubt das Verwalten von Zielen über die API.
• Datenschutz und Drittdienste: Was bei der Übertragung personenbezogener Daten an eigene Systeme zu beachten ist.
• Formulare: Lead-Formulare erzeugen Tickets, Kunden und Karten, die ebenfalls Webhooks auslösen.