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 Verwaltung > Vorgänge > Vorlagen, Verwaltung > Leistungen > Vorlagen oder Verwaltung > Protokolle > Muster anlegen können.

Webhooks finden Sie unter Verwaltung > 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 Neuen Webbhook anlegen 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

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

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 ein 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)

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 eine 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
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 das 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.