Webhooks in Nachrichten-Vorlagen

Generelle Informationen

Was sind Webhook-Links in Nachrichten?

Webhook-Links ermöglichen es, direkt aus Nachrichten-Vorlagen heraus Webhooks aufzurufen. Dies erlaubt es, interaktive Links in E-Mails einzubetten, über die Kunden oder Mitarbeiter Aktionen ausführen können, ohne sich in DocBee anmelden zu müssen.

Wann sollten Sie Webhook-Links in Nachrichten verwenden?

Falls einer oder mehrere der folgenden Punkte zutreffen, empfehlen wir den Einsatz von Webhook-Links in Nachrichten:

• Sie möchten, dass Kunden Aktionen direkt aus E-Mails heraus ausführen können (z.B. Problem-Bestätigung, Daten erfassen)
• Sie benötigen strukturierte Datenerfassung über Protokolle ohne Kunden-Login
• Sie wollen den Workflow vereinfachen, indem Sie Links direkt in Nachrichten einbetten
• Sie möchten automatisierte Prozesse mit Benutzerinteraktion kombinieren

Weitere Informationen finden Sie in der Nachrichten-Dokumentation und der Webhooks-Dokumentation.

Grundlagen

Der docbee_webhooklink Tag

Mit dem docbee_webhooklink Tag können Sie Webhook-Links direkt in Nachrichten-Vorlagen erstellen. Dieser Tag wird innerhalb der Nachrichten-Logik verwendet und generiert einen klickbaren Link, der den entsprechenden Webhook aufruft.

Wichtige Parameter:

Parameter	Pflichtfeld	Beschreibung
id	Ja	ID des Webhooks
personInChargeId	Nein*	ID eines Benutzers oder Queue
customerId	Nein*	ID des Kunden
locationId	Nein	ID des Kunden-Standorts
contactId	Nein	ID des Kunden-Kontakts
ticketId	Nein	ID eines Vorgangs
docBeeDocumentId	Nein	ID einer Leistung
name	Nein	Optionaler Name des Links
style	Nein	Optionale CSS-Styles für die Darstellung des Links

*Bei Protokoll-Webhooks muss die personInChargeId und die customerId gesetzt werden und Queues sind nicht erlaubt als Verantwortlicher.

Hinweis: Bei einem Protokoll-Webhook wird immer die Verknüpfung zum Vorgang hergestellt, auch wenn dieser geschlossen sein sollte. Der Vorgang verbleibt im abgeschlossenen Zustand.

Bei Protokoll-Webhooks kann das Tag außerdem beliebig viele data-<Platzhaltername>-Attribute tragen, die Felder des aufgerufenen Protokolls automatisch aus dem Vorgang oder verknüpften Objekten vorausfüllen – siehe Beispiel 3.

Weitere Details finden Sie in der vollständigen Dokumentation zum docbee_webhooklink Tag.

Beispiel 1: Problem-Bestätigung über Vorgangs-Nachricht

Szenario

Ein Kunde meldet ein Problem. Nachdem das Problem behoben wurde, soll der Kunde bestätigen können, dass alles funktioniert, indem er auf einen Link in einer E-Mail klickt. Diese Bestätigung wird dann als Nachricht an den Vorgang angehängt.

Schritt-für-Schritt-Anleitung

Schritt 1: Webhook anlegen

1. Navigieren Sie zu Administration > Webhooks > Liste
2. Klicken Sie auf Hinzufügen
3. Geben Sie einen Namen ein (z.B. "Problem gelöst bestätigen")
4. Wählen Sie als Typ den Typ Nachricht
5. Wählen Sie eine Nachrichten-Vorlage aus, die verwendet werden soll, wenn der Webhook aufgerufen wird
6. Speichern Sie den Webhook

Hinweis: Notieren Sie sich die ID des Webhooks, da Sie diese später in der Nachrichten-Vorlage benötigen. Sie finden die ID in der Browser Adresszeile.

Schritt 2: Nachrichten-Vorlage mit Webhook-Link erstellen

1. Navigieren Sie zu Administration > Nachrichten > Vorlagen
2. Erstellen Sie eine neue Nachrichten-Vorlage oder bearbeiten Sie eine bestehende
3. Wählen Sie als Typ einen passenden Typ aus (z.B. Nachrichtenversand (Vorgang))
4. Geben Sie einen Betreff ein (z.B. "Problem sollte behoben sein - Bitte bestätigen")
5. Fügen Sie im Inhalt folgenden Code ein:

Sehr geehrte Damen und Herren,

das Problem sollte nun behoben sein. Bitte bestätigen Sie dies, indem Sie auf den folgenden Link klicken:

<docbee_webhooklink id='[WEBHOOK_ID]'
                    ticketId='ticket.id' 
                    name='Problem gelöst bestätigen' />

Mit freundlichen Grüßen
Ihr DocBee Team

Wichtig: Ersetzen Sie [WEBHOOK_ID] mit der tatsächlichen ID des in Schritt 1 erstellten Webhooks.

Schritt 3: Nachricht versenden

Wenn Sie nun eine Nachricht an einen Vorgang versenden und diese Nachrichten-Vorlage verwenden, wird der Webhook-Link automatisch in die E-Mail eingefügt. Der Kunde kann auf den Link klicken, um die Bestätigung zu senden.

Wie funktioniert es?

• Beim Klick auf den Link wird der Webhook aufgerufen
• Der Webhook erstellt eine Nachricht an den Vorgang (basierend auf der im Webhook hinterlegten Nachrichten-Vorlage)
• Die Nachricht wird automatisch mit dem Vorgang verknüpft
• Der Verantwortliche des Vorgangs wird über die Bestätigung informiert

Beispiel 2: Protokoll-Webhook für strukturierte Datenabfrage

Szenario

Ein Kunde benötigt einen neuen AD-Benutzer. Statt die Daten per E-Mail zu senden, soll der Kunde ein strukturiertes Formular (Protokoll) ausfüllen können. Der Link zum Formular wird in einer E-Mail versendet.

Schritt-für-Schritt-Anleitung

Schritt 1: Protokoll-Muster erstellen

1. Navigieren Sie zu Administration > Protokolle > Muster
2. Klicken Sie auf Hinzufügen
3. Geben Sie einen Namen ein (z.B. "Neuer AD-Benutzer")
4. Fügen Sie die benötigten Felder hinzu (z.B. Vorname, Nachname, E-Mail, Abteilung, etc.)
5. Speichern Sie das Protokoll-Muster
6. Geben Sie das Protokoll-Muster frei

Schritt 2: Webhook anlegen

1. Navigieren Sie zu Administration > Webhooks > Liste
2. Klicken Sie auf Hinzufügen
3. Geben Sie einen Namen ein (z.B. "AD-Benutzer Daten erfassen")
4. Wählen Sie als Typ den Typ Protokoll
5. Wählen Sie das in Schritt 1 erstellte Protokoll-Muster aus
6. Speichern Sie den Webhook

Hinweis: Notieren Sie sich die ID des Webhooks, da Sie diese später in der Nachrichten-Vorlage benötigen.

Schritt 3: Nachrichten-Vorlage mit Protokoll-Webhook-Link erstellen

1. Navigieren Sie zu Administration > Nachrichten > Vorlagen
2. Erstellen Sie eine neue Nachrichten-Vorlage oder bearbeiten Sie eine bestehende
3. Wählen Sie als Typ einen passenden Typ aus (z.B. Nachrichtenversand (Vorgang))
4. Geben Sie einen Betreff ein (z.B. "Bitte AD-Benutzer Daten erfassen")
5. Fügen Sie im Inhalt folgenden Code ein:

Sehr geehrte Damen und Herren,

bitte füllen Sie das folgende Formular aus, um die Daten für den neuen AD-Benutzer zu erfassen:

<docbee_object input='ticket.customer' var='ticketCustomer'>
<docbee_object input='ticket.owner' var='ticketOwner'>
<docbee_webhooklink id='[WEBHOOK_ID]' 
                    personInChargeId='ticketOwner.id' 
                    customerId='ticketCustomer.id' 
                    ticketId='ticket.id' 
                    name='AD-Benutzer Daten erfassen' />
</docbee_object>
</docbee_object>

Mit freundlichen Grüßen
Ihr DocBee Team

Wichtig: Ersetzen Sie [WEBHOOK_ID] mit der tatsächlichen ID des in Schritt 2 erstellten Webhooks.

Wichtig: Bei Protokoll-Webhooks müssen personInChargeId und customerId zwingend gesetzt werden.

Schritt 4: Nachricht versenden

Wenn Sie nun eine Nachricht an einen Vorgang versenden und diese Nachrichten-Vorlage verwenden, wird der Protokoll-Webhook-Link automatisch in die E-Mail eingefügt. Der Kunde kann auf den Link klicken, um das Protokoll auszufüllen.

Wie funktioniert es?

• Beim Klick auf den Link wird der Protokoll-Webhook aufgerufen
• Der Kunde sieht ein Formular basierend auf dem Protokoll-Muster
• Nach dem Ausfüllen wird ein Protokoll erstellt und mit dem Vorgang verknüpft
• Der Verantwortliche des Vorgangs wird über das neue Protokoll informiert
• Das Protokoll kann später als PDF exportiert werden

Beispiel 3: Protokoll-Felder automatisch vorausfüllen

Szenario

Für die IT-Ausstattung eines neuen Mitarbeiters soll ein Protokoll ausgefüllt werden. Referenznummer und Starttermin stehen bereits am Vorgang, der Name des Mitarbeiters am verknüpften Kontakt. Diese Werte sollen nicht erneut eingetippt werden müssen, sondern beim Öffnen des Protokolls automatisch vorausgefüllt sein. Zusätzlich soll das Feld Bearbeitungsstatus immer mit einem festen Wert vorbelegt werden, unabhängig vom Vorgang.

Schritt-für-Schritt-Anleitung

Schritt 1: Protokoll-Muster erstellen

1. Navigieren Sie zu Administration > Protokolle > Muster
2. Legen Sie ein Protokoll-Muster mit den benötigten Feldern an, z. B. mit den Platzhalter-Namen REFERENZNUMMER, STARTTERMIN, MITARBEITERNAME und BEARBEITUNGSSTATUS
3. Speichern und geben Sie das Protokoll-Muster frei

Schritt 2: Webhook anlegen

1. Navigieren Sie zu Administration > Webhooks > Liste
2. Klicken Sie auf Hinzufügen
3. Geben Sie einen Namen ein (z. B. „IT-Ausstattung erfassen")
4. Wählen Sie als Typ den Typ Protokoll und das in Schritt 1 erstellte Protokoll-Muster
5. Speichern Sie den Webhook und notieren Sie sich die ID

Schritt 3: Nachrichten-Vorlage mit vorausfüllenden data-*-Attributen erstellen

1. Navigieren Sie zu Administration > Nachrichten > Vorlagen
2. Erstellen Sie eine neue Nachrichten-Vorlage oder bearbeiten Sie eine bestehende
3. Fügen Sie im Inhalt ein data-<Platzhaltername>-Attribut je vorauszufüllendem Feld hinzu. Der Teil nach data- muss dabei dem Platzhalter-Namen des Ziel-Feldes im Protokoll-Muster entsprechen. Ein Attribut kann sowohl auf einen Vorgangs-/Kontakt-Wert verweisen als auch direkt einen festen Wert enthalten:

<docbee_object input='ticket.customer' var='ticketCustomer'>
<docbee_object input='ticket.owner' var='ticketOwner'>
<docbee_webhooklink id='[WEBHOOK_ID]'
                    personInChargeId='ticketOwner.id'
                    customerId='ticketCustomer.id'
                    ticketId='ticket.id'
                    name='IT-Ausstattung erfassen'
                    data-referenznummer='ticket.referenceNumber'
                    data-starttermin='ticket.customFields[STARTTERMIN]'
                    data-mitarbeitername='contact.name'
                    data-bearbeitungsstatus='Erstkontakt' />
</docbee_object>
</docbee_object>

Wichtig: Ersetzen Sie [WEBHOOK_ID] mit der tatsächlichen ID des in Schritt 2 erstellten Webhooks.

Schritt 4: Nachricht versenden

Beim Klick auf den Link öffnet sich das Protokoll mit den Feldern REFERENZNUMMER, STARTTERMIN, MITARBEITERNAME und BEARBEITUNGSSTATUS bereits ausgefüllt; alle übrigen Felder bleiben wie gewohnt leer zum Ausfüllen.

Wie funktioniert es?

• Beim Rendern der Nachricht versucht jedes data-<Platzhaltername>-Attribut zunächst, seinen Wert als Pfad (z. B. ticket.referenceNumber) gegen die im Nachrichtentyp gebundene Variable aufzulösen
• Lässt sich der Wert nicht als Pfad auflösen – etwa weil er gar keinen Punkt enthält (Freitext, eine Zahl, ein Datum) oder auf keine tatsächlich gebundene Variable verweist –, wird er unverändert als fester Wert übernommen. Dafür gibt es keine eigene Schreibweise: data-bearbeitungsstatus='Erstkontakt' funktioniert allein dadurch, dass Erstkontakt sich nicht auflösen lässt
• Fehlt ein referenzierter Wert für den aktuellen Vorgang oder das aktuelle Objekt (der Pfad ist gültig, das Feld aber leer), bleibt nur das betroffene Feld leer
• Ein Ziel-Feld vom Typ Mehrfachauswahl lässt sich aktuell nur über eine literale, durch Komma getrennte Liste von IDs befüllen, z. B. data-auswahl='3,7,12' — eine Wildcard-Referenz auf ein Mehrfachauswahl-Zusatzfeld liefert die hinterlegte Namensliste, keine IDs
• Ein optionales data-<Platzhaltername>-group='<Zahl>' ordnet den Wert einer bestimmten Zeile eines Mehrfachgruppen-Feldes zu

Best Practices

Wann welche Webhook-Typen verwenden?

Webhook-Typ	Verwendungszweck
Nachricht	Wenn eine einfache Bestätigung oder Rückmeldung benötigt wird
Protokoll	Wenn strukturierte Daten erfasst werden sollen (z.B. Formulare, Checklisten)
Vorgang	Wenn ein neuer Vorgang erstellt werden soll
Leistung	Wenn eine neue Leistung erstellt werden soll
Automatisierung	Wenn komplexe Automatisierungen ausgelöst werden sollen, z.B. Vorgang ändern

Wichtige Hinweise zu Protokoll-Webhooks

• personInChargeId und customerId sind Pflichtfelder: Bei Protokoll-Webhooks müssen beide Parameter gesetzt werden
• Queues sind nicht erlaubt: Als Verantwortlicher kann nur ein Benutzer, nicht aber eine Queue verwendet werden
• Verknüpfung zum Vorgang: Das Protokoll wird automatisch mit dem Vorgang verknüpft, auch wenn dieser geschlossen ist

Tipps zur Gestaltung der Links

• Verwenden Sie aussagekräftige Namen: Der name-Parameter sollte klar beschreiben, was beim Klick passiert
• Nutzen Sie CSS-Styles: Mit dem style-Parameter können Sie Links im HTML hervorheben (z.B. style='color:#28a745; font-weight:bold;' für grüne, fette Links)
• Testen Sie die Links: Stellen Sie sicher, dass alle benötigten Parameter korrekt gesetzt sind

Beispiel für verschiedene Link-Styles

<!-- Grüner Link für Bestätigungen -->
<docbee_webhooklink id='1' name='Bestätigen' style='color:#28a745; font-weight:bold;' />

<!-- Blauer Link für Formulare -->
<docbee_webhooklink id='2' name='Formular ausfüllen' style='color:#007bff; font-weight:bold;' />

<!-- Roter Link für wichtige Aktionen -->
<docbee_webhooklink id='3' name='Wichtig' style='color:#dc3545; font-weight:bold; text-decoration:underline;' />

FAQ

Warum funktioniert mein Webhook-Link nicht?

Mögliche Ursachen:

1. Falsche Webhook-ID: Überprüfen Sie, ob die ID im docbee_webhooklink Tag korrekt ist
2. Fehlende Parameter: Bei Protokoll-Webhooks müssen personInChargeId und customerId gesetzt sein
3. Webhook wurde gelöscht: Prüfen Sie, ob der Webhook noch in der Webhook-Liste vorhanden ist
4. Falsche Objekt-Referenzen: Stellen Sie sicher, dass die verwendeten Objekte (z.B. ticket.customer) existieren

Warum erhalte ich einen Fehler bei Protokoll-Webhooks?

Protokoll-Webhooks haben spezielle Anforderungen:

• personInChargeId ist Pflicht: Dieser Parameter muss gesetzt werden und darf keine Queue sein
• customerId ist Pflicht: Dieser Parameter muss gesetzt werden
• Verknüpfung zum Vorgang: Das Protokoll wird automatisch mit dem Vorgang verknüpft

Stellen Sie sicher, dass beide Parameter korrekt gesetzt sind:

<docbee_object input='ticket.customer' var='ticketCustomer'>
<docbee_object input='ticket.owner' var='ticketOwner'>
<docbee_webhooklink id='[WEBHOOK_ID]' 
                    personInChargeId='ticketOwner.id' 
                    customerId='ticketCustomer.id' 
                    ticketId='ticket.id' />
</docbee_object>
</docbee_object>

Wie kann ich die Webhook-ID herausfinden?

Die Webhook-ID finden Sie in der Webhook-Liste unter Administration > Webhooks > Liste. Die ID wird in der Liste angezeigt oder kann über die Aktionen des Webhooks eingesehen werden.

Kann ich mehrere Webhook-Links in einer Nachricht verwenden?

Ja, Sie können mehrere docbee_webhooklink Tags in einer Nachrichten-Vorlage verwenden. Jeder Link kann zu einem anderen Webhook führen.

Beispiel:

Bitte wählen Sie eine Aktion:

<docbee_webhooklink id='1' name='Problem gelöst' />
<docbee_webhooklink id='2' name='Problem besteht weiterhin' />

Werden die Links in HTML-E-Mails korrekt angezeigt?

Ja, die Webhook-Links werden in HTML-E-Mails als klickbare Links dargestellt. Der name-Parameter wird als Link-Text verwendet, und der style-Parameter wird als CSS-Style angewendet.

Kann ich Webhook-Links auch in Text-E-Mails verwenden?

Ja, Webhook-Links funktionieren auch in Text-E-Mails. Der Link wird als URL dargestellt, die der Empfänger anklicken kann.