Webhooks

Generelle Informationen

Was sind Webhooks?

Webhooks (früher Externe Ereignisse) ermöglichen es, dass über HTTP-Aufrufe Vorgänge, Leistungen oder Protokolle angelegt bzw. ausgefüllt werden.

Wann sollten Sie Webhooks verwenden?

Falls einer oder mehrere der folgenden Punkte zutreffen, empfehlen wir den Einsatz von Webhooks.

• Erfassung von strukturierten Daten durch Kunden ohne Kunden Login
• Verwendung von Monitoring-Systemen, die noch nicht ans DocBee angebunden sind, aber HTTP-Aufrufe erzeugen können
• Automatisierung von Leistungserstellungen bei z.B. erfolgreicher Backup Check
• Fehlermeldung eines Kunden über einen QR-Code oder über einen Link ohne Anmeldung

Webhooks

Webhooks basieren auf Vorlagen oder Protokoll-Muster, die Sie je nach Typ unter Administration > Webhooks > Liste > Hinzufügen anlegen können.

Webhooks finden Sie unter Administration > Webhooks.

Einstellungen

Webhooks müssen erst generell aktiviert werden. Das Aktivieren erzeugt automatisch einen Schlüssel, falls dieser noch nicht existiert. Dieser Schlüssel dient als Bestimmung, ob das externe Ereignis gültig ist.

Wichtig: Falls der Schlüssel erneuert wird, sind alle alten Links nicht mehr gültig und müssen neu verteilt werden!

Neuer Webhook

Um ein neues Webhooks anzulegen, wird auf die Schaltfläche Hinzufügen geklickt. Dies öffnet einen Dialog zum Anlegen eines neuen Webhooks.

Allgemeine

Feld	Beschreibung
Name	Name des Webhooks
Typ	Definiert den Typ des Webhooks => Was soll auf Aufruf passieren
Schwellwert (in Sekunden)	Wie häufig darf dieser Webhook aufgerufen werden? Falls hier z.B. 30 Sekunden eingegeben wird, darf der Aufruf nur alle 30 Sekunden aufgerufen werden
Abschluss-Text	Text, der dem Benutzer angezeigt wird, wenn der Webhook erfolgreich ausgeführt wurde (Kann Platzhalter enthalten)

Protokoll

Definiert, dass ein Protokoll ausgefüllt werden soll.

Feld	Beschreibung
Protokoll-Muster	Ein Protokoll-Muster
E-Mail notwendig?	Soll vorher nach einer E-Mail Adresse gefragt werden zur Bestimmung des Kunden-Kontakts

Leistung

Definiert, dass eine Leistung angelegt werden soll.

Feld	Beschreibung
Leistungs-Vorlage	Eine Leistungs-Vorlage
Formular anzeigen	Definiert ob ein Formular angezeigt werden soll (Siehe Formular
Dateianhang erlauben	Definiert ob ein Datei Upload erlaubt angezeigt wird oder nicht

Vorgang

Definiert, dass ein Vorgang angelegt werden soll.

Feld	Beschreibung
Vorgangs-Vorlage	Eine Vorgangs-Vorlage
Formular anzeigen	Definiert ob ein Formular angezeigt werden soll (Siehe Formular
Dateianhang erlauben	Definiert ob ein Datei Upload erlaubt angezeigt wird oder nicht

Nachricht

Definiert, dass eine Vorgangs- oder Leistungsnachricht angelegt werden soll. Als Absender-Name wird der Name des Webhooks verwendet.

Feld	Beschreibung
Nachrichten-Vorlage	Eine Nachrichten-Vorlage

Automatisierung

Definiert, dass eine Automatisierung gestartet werden soll.

Feld	Beschreibung
Automatisierung	Eine Automatisierung vom Typ Vorgang-Webhook oder Leistung-Webhook

Weiterleitung

Feld	Beschreibung
Statische URL	Die URL zu der nach Erfolgreicher Ausführung weitergeleitet werden soll
Webhook	Ein Webhook der als Weiterleitung verwendet wird. Die Ausgewählten Daten aus diesem Webhook werden für den nächsten Webhook wieder verwendet

Webhook Auswahl

Erlaubt dem Nutzer die Auswahl eines Webhooks aus einer Liste. Die ausgewählten Daten aus diesem Webhook werden für den nächsten Webhook wieder verwendet.

Feld	Beschreibung
Elemente	Eine Liste an Webhooks, die dem Nutzer zur Auswahl bereitgestellt werden.

Die Elemente haben folgende Felder:

Feld	Beschreibung
Webhook	Ein Webhook der als Auswahl-Element verwendet wird.
Bezeichnung	Eine optionale Bezeichnung, die dem Nutzer angezeigt wird.
Icon	Ein optionales Icon, das dem Nutzer angezeigt wird.

Link Generierung

Nachdem ein Webhook angelegt worden ist, kann der zugehörige Link generiert werden. Dafür wird in der Liste von Webhooks die Schaltfläche in Aktionen geklickt. Dies öffnet einen Dialog, in dem zusätzliche Parameter gesetzt werden können. (Falls einige Felder deaktiviert sind, wurden Sie schon in der Vorlage definiert und können somit nicht mehr überschrieben werden.)

Für Webhooks der Typen Nachricht anlegen und Automatisierung ausführen kann in der Liste kein Link generiert werden, stattdessen lassen sich Webhooks dieses Typs in Nachrichten-Vorlagen verwenden (siehe docbee_webhooklink).

Formular

Webhook bieten die Möglichkeit bei Aufruf vom Typ Leistung erstellen oder Vorgang erstellen des Links ein Formular anzuzeigen, in dem der Name, E-Mail Adresse, ein Betreff und eine Nachricht (optional) abgefragt wird.

Falls ein Vorgang angelegt wird, werden diese Informationen automatisch als Vorgangs-Nachricht hinterlegt und der Kunde wird via E-Mail über den neuen Vorgang informiert (Wie es z.B. beim Mail Parser der Fall sein würde)

Im Fall, dass dem externen Ereignis nicht über die Vorlage oder über Parameter ein Kontakt zugewiesen worden ist, wird versucht, dem Kontakt anhand der im Formular übergebenen E-Mail Adresse zu finden.

Platzhalter

Es können in den Vorlagen Platzhalter verwendet werden, die bei Vorgängen (Beschreibung, Interne Beschreibung) und Leistungen (Tätigkeits-Name, Tätigkeits-Beschreibung, Tätigkeits-Interne Beschreibung) durch Werte ersetzt werden.

Name	Beschreibung
%TELEFON%	Die Telefonnummer, die als Parameter contactPhone übergeben wurde.
%NACHRICHT%	Die Nachricht, die im Formular eingetragen wurde oder per Parameter message übergeben wurde.
%EMAIL%	Die E-Mail Adresse, die beim Formular eingetragen wurde
%NAME%	Der Name, der beim Formular eingetragen wurde
%BETREFF%	Der Betreff, der beim Formular eingetragen wurde

Parameter

Webhooks können mit optionalen Parameter versehen werden.

Hinweis: Alle Parameter müssen URL kodiert werden, damit Sie korrekt verarbeitet werden können.

Die Parameter können direkt an die URL aus der Link-Generierung angehangen werden in der Form &parameterName=wert

Name	Beschreibung	Beispielwerte
owner	Die Benutzer ID des Verantwortlichen des neuen Vorgangs / der neuen Leistung. Dieser Parameter wird nur berücksichtigt, falls kein Verantwortlicher in der Vorlage des Vorgangs oder der Leistung gesetzt ist.	1
ownerUsername	Der Benutzername ohne Mandanten Kürzel z.B. DOCBEE/m.mustermann => m.mustermann Dieser Parameter wird nur berücksichtigt, falls der Parameter owner nicht gesetzt ist und kein Verantwortlicher in der Vorlage des Vorgangs oder der Leistung gesetzt ist.	m.mustermann
ownerEmail	Die E-Mail Adresse des Verantwortlichen des neuen Vorgangs / der neuen Leistung. Dieser Parameter wird nur berücksichtigt, falls die Parameter owner und ownerUsername nicht gesetzt sind und kein Verantwortlicher in der Vorlage des Vorgangs oder der Leistung gesetzt ist.	info@docbee.com
object	Die Kunden-Objekt ID wird in den Vorgang bzw. die Tätigkeiten der Leistung gesetzt. Anhand des Kunden-Objekts werden auch automatisch der Kunde und der Standort gesetzt. Dieser Parameter wird nur berücksichtigt, falls kein Kunden-Objekt in der Vorlage des Vorgangs oder den Tätigkeiten der Leistungen gesetzt ist.	1
contact	Die Kontakt ID des Kontaktes des neuen Vorgangs / der neuen Leistung. Anhand des Kontaktes werden auch automatisch der Kunde und der Standort gesetzt. Dieser Parameter wird nur berücksichtigt, falls kein Kontakt in der Vorlage des Vorgangs oder der Leistung gesetzt ist und der Kontakt zu vielleicht gesetzten Kunden und/oder Standorten passt.	1
contactPhone	Die Telefonnummer des Kontaktes des neuen Vorgangs / der neuen Leistung. Anhand des Kontaktes werden auch automatisch der Kunde und der Standort gesetzt. Dieser Parameter wird nur berücksichtigt, falls der Parameter contact nicht gesetzt ist und kein Kontakt in der Vorlage des Vorgangs oder der Leistung gesetzt ist und der Kontakt zu vielleicht gesetzten Kunden und/oder Standorten passt.	0511 / 123459 - 555
contactEmail	Die E-Mail Kontaktes des neuen Vorgangs / der neuen Leistung. Anhand des Kontaktes werden auch automatisch der Kunde und der Standort gesetzt. Dieser Parameter wird nur berücksichtigt, falls der Parameter contact nicht gesetzt ist und kein Kontakt in der Vorlage des Vorgangs oder der Leistung gesetzt ist und der Kontakt zu vielleicht gesetzten Kunden und/oder Standorten passt.	info@docbee.com
location	Die Standort ID des neuen Vorgangs / der neuen Leistung. Dieser Parameter wird nur berücksichtigt, falls die Parameter contact und contactPhone nicht gesetzt sind und kein Standort in der Vorlage des Vorgangs oder der Leistung gesetzt ist und der Standort zu vielleicht gesetzten Kunden passt	1
customer	Die ID des Kunden des neuen Vorgangs / der neuen Leistung. Dieser Parameter wird nur berücksichtigt, falls die Parameter contact, contactPhone und location nicht gesetzt sind und kein Kunde in der Vorlage des Vorgangs oder der Leistung gesetzt ist.	1
customerId	Die Kundennummer des Kunden des neuen Vorgangs / der neuen Leistung. Dieser Parameter wird nur berücksichtigt, falls die Parameter contact, contactPhone, location und customer nicht gesetzt sind und kein Kunde in der Vorlage des Vorgangs oder der Leistung gesetzt ist.	A123456
message	Eine Nachricht, die als Platzhalter verwendet werden kann	Beispiel-Nachricht

FAQ

Warum liefert mir der Webhook "400 Oops! Fehlerhafte Anfrage"?

Der Webhook hat nicht alle benötigten Parameter z.B. keinen Kunden bei Leistungen oder der Webhook wurde gelöscht.

Bitte überprüfen Sie den verwendeten Link.

Warum liefert mir der Webhook mit Protokoll-Abschluss den Fehler "Bad Request"?

Der Webhook wurde in DocBee gelöscht und kann deswegen nicht mehr verwendet werden. Bitte prüfen Sie daher, ob der Webhook noch in der Webhook Liste vorhanden ist und erstellen Sie gegebenenfalls einen neuen.