Webhooks

Webhooks erleichtern die Kommunikation mit Drittanwendungen, indem sie jedes Mal sofortige Webbenachrichtigungen senden, wenn in Zoho Books ein Ereignis auftritt. Mit Webhooks können Sie HTTP- und HTTPS-URLs konfigurieren und diese mit Workflow-Regeln verknüpfen, um den Benachrichtigungsprozess zu automatisieren. Lesen Sie unser Hilfedokument zu Webhook-Beispielen, um mehr darüber zu erfahren, wann und wie Sie Webhooks verwenden können.

Für allgemeine Informationen zu Webhooks besuchen Sie webhooks.org.

Szenario: Angenommen, Sie verwenden eine separate Fulfillment-Anwendung, um Bestellungen zu versenden. Jedes Mal, wenn in Zoho Books ein Verkaufsauftrag erstellt wird, möchten Sie, dass diese Anwendung die Bestelldetails sofort erhält. Indem Sie einen Webhook mit der URL der Anwendung einrichten und ihn mit einer Workflow-Regel verknüpfen, sendet Zoho Books die Bestelldetails an die Anwendung, sobald ein Verkaufsauftrag erstellt wird, sodass Ihr Team mit dem Fulfillment beginnen kann, ohne die Daten erneut eingeben zu müssen.

Erstellen eines Webhooks

Um einen Webhook einzurichten:

Gehen Sie zu Einstellungen in der oberen rechten Ecke der Seite.
Wählen Sie Workflow-Aktionen unter Automatisierung.
Wählen Sie im Bereich Workflow-Aktionen Webhooks.
Klicken Sie auf + Neuer Webhook in der oberen rechten Ecke.

Füllen Sie die erforderlichen Details für die folgenden Felder aus.

Feldname	Beschreibung
URL und Parameter	Geben Sie die URL ein (URL der API des externen Dienstanbieters) und wählen Sie den Ereignistyp aus, für den der Webhook ausgelöst werden soll. Sie können auch Platzhalter einfügen, indem Sie auf die Schaltfläche + Neuer Platzhalter klicken. Wählen Sie den Typ der API-Methode: PUT, POST oder DELETE. Standardmäßig wählt das System die Methode POST aus. POST: Fordert an, dass die gesendeten Daten als neu betrachtet werden müssen. PUT: Fordert an, dass die gesendeten Daten als modifizierte Version der bereits vorhandenen Version betrachtet werden müssen. DELETE: Fordert an, dass die Daten gelöscht werden müssen.
Benutzerdefinierte Parameter	Sie können dem Webhook benutzerdefinierte Parameter wie AuthToken, Sicherheitstoken, API-Schlüssel usw. hinzufügen, anhand derer die URL ergänzt wird. Geben Sie den erforderlichen Parameter unter Parametername und den entsprechenden Wert unter Parameterwert ein. Wenn Sie mehrere Parameter hinzufügen möchten, klicken Sie auf + Neuer Parameter.
HTTP-Header	Im Abschnitt HTTP-Header können Sie alle zusätzlichen Informationen einfügen, die in die HTTP-Anfrage aufgenommen werden sollen. Geben Sie einen Schlüssel unter Parametername und einen Wert unter Parameterwert ein. Klicken Sie auf + Neuer Header, wenn Sie zusätzliche Header hinzufügen möchten.
Sicherheitseinstellungen	Wählen Sie aus, wie Sie den Zugriff auf die URL des externen Dienstanbieters autorisieren möchten. Allgemein: Wählen Sie diesen Typ, wenn Sie diesen Webhook mit Basisautorisierung, API-Autorisierung oder ohne jegliche Autorisierung erstellen möchten. Verbindungen: Wählen Sie diesen Typ, wenn Sie eine Verbindung verwenden möchten, die zwischen Zoho Books und einer Drittanwendung erstellt wurde, um diesen Webhook zu autorisieren. Sie können den Webhook auch mit einem geheimen Token sichern, das nach dem Erstellen des Webhooks nicht mehr bearbeitet oder angezeigt werden kann. Aktivieren Sie das Kontrollkästchen Ich möchte diesen Webhook mit einem geheimen Token sichern und geben Sie den geheimen Token in das darunterliegende Feld ein. Dies hilft zu überprüfen, ob der Webhook von Zoho Books gesendet wurde. Er sollte alphanumerisch sein und zwischen 12 und 50 Zeichen liegen.
Body	Wählen Sie im Abschnitt Body aus, wie Sie die Daten senden möchten. Sie können aus den Body-Parametern Standard-Nutzdaten, x-www-form-urlencoded und Raw wählen. Standard-Nutzdaten: Im Standard-Nutzdatenformat werden alle mit dem Modul verbundenen Parameter im Inhaltstyp application/JSON an den Anforderungstextkörper gesendet. x-www-form-urlencoded: Im x-www-form-urlencoded-Format werden die Daten kodiert und an den Server gesendet. Raw: Im Raw-Format können Sie die Parameter auswählen, die an den Anforderungstextkörper gesendet werden. Der Inhaltstyp ist application/JSON.

Klicken Sie auf Speichern und Ausführen, um zu überprüfen, ob der Webhook ordnungsgemäß funktioniert, oder klicken Sie auf Speichern, wenn Sie ihn später ausführen möchten.

Hinweis: Wenn Sie Webhooks einrichten, werden alle Kontaktdaten Ihrer Zoho Books-Organisation (Name, Telefonnummer, Adresse und E-Mail-Adresse) mit der URL geteilt, die Sie benachrichtigen möchten.

Webhooks mit Workflow-Regeln verknüpfen

Die von Ihnen erstellten Webhooks sollten mit Workflow-Regeln verknüpft werden, damit sie automatisch ausgelöst werden, wenn die erforderlichen Bedingungen erfüllt sind. Um Webhooks mit Workflow-Regeln zu verknüpfen:

Gehen Sie zu Einstellungen.
Wählen Sie Workflow-Regeln unter Automatisierung.
Klicken Sie auf + Neue Workflow-Regel in der oberen rechten Ecke.
Geben Sie die erforderlichen Details ein. Siehe Workflow-Regeln.
Wählen Sie unter Aktionen Webhooks als Typ und wählen Sie den Webhook aus, den Sie mit der Workflow-Regel verknüpfen möchten.
Klicken Sie auf Speichern.

Jetzt wird die Workflow-Regel jedes Mal ausgelöst, wenn die Kriterien erfüllt sind, wodurch wiederum der Webhook ausgelöst wird.

Zustellungsverhalten

Wenn ein Webhook ausgelöst wird, versucht Zoho Books, ihn an Ihre Endpunkt-URL zuzustellen. Die folgenden Abschnitte erläutern, wie Zustellungen ausgewertet, wiederholt und in den Workflowprotokollen erfasst werden.

Zustellungsstatus

Jede Webhook-Zustellung führt in den Workflowprotokollen zu einem der folgenden Status:

Erfolg: Der Endpunkt hat innerhalb des Zeitlimits mit einem 2xx-Statuscode geantwortet.
Fehlgeschlagen: Die Zustellung hat eine Nicht-2xx-Antwort erhalten oder es kam zu einer Zeitüberschreitung.
Übersprungen: Die Zustellung wurde nicht versucht, in der Regel, wenn das Tageslimit erreicht ist.

Wenn für eine fehlgeschlagene Zustellung eine Wiederholung geplant ist, wird die nächste Wiederholungszeit neben dem Status angezeigt.

Verhalten bei Zeitüberschreitung

Das Verbindungstimeout ist auf 5 Sekunden und das Lesetimeout auf 10 Sekunden festgelegt. Wenn eines der beiden Limits überschritten wird, wird der Versuch als fehlgeschlagen markiert.

Was als Fehler gilt

Jede Nicht-2xx-Antwort, einschließlich 3xx-Weiterleitungen, 4xx-Clientfehlern, 5xx-Serverfehlern und Zeitüberschreitungen, wird als Fehler behandelt und kommt für eine Wiederholung infrage. Wenn für Ihre Endpunkt-URL eine Weiterleitung konfiguriert ist, aktualisieren Sie die Webhook-URL direkt auf das endgültige Ziel.

Standard-Wiederholungsrichtlinie

Fehlgeschlagene Webhooks werden automatisch genau 5 Mal wiederholt, bevor sie als erschöpft markiert werden. Wiederholte Zustellungen enthalten dieselben ursprünglichen Nutzdaten, gestalten Sie Ihren Endpunkt daher so, dass er doppelte Zustellungen sicher verarbeiten kann.

Benutzerdefinierte Wiederholungsrichtlinie

Sie können bis zu 20 Wiederholungsversuche konfigurieren, zusammen mit der Auswahl einer Wiederholungsmethode: Festes Intervall (dieselbe Wartezeit zwischen den einzelnen Wiederholungen), Additiv (die Wartezeit erhöht sich nach jeder Wiederholung um einen festen Betrag) oder Multiplikativ (die Wartezeit wird nach jeder Wiederholung mit einem festgelegten Faktor multipliziert). Um dies einzurichten, öffnen Sie den Tab Webhooks unter Konfigurieren der Fehlereinstellungen auf der Seite Workflowprotokolle.

Fehlerbenachrichtigungen

Wenn ein Webhook 20 Mal oder häufiger nacheinander fehlschlägt, wird eine Benachrichtigung an die Empfänger gesendet, die unter dem Tab Webhooks in Konfigurieren der Fehlereinstellungen auf der Seite Workflowprotokolle konfiguriert wurden.

Manuelle Wiederholung

Erschöpfte Webhooks können jederzeit manuell über die Workflowprotokolle wiederholt werden. Manuelle Wiederholungen werden nicht auf das tägliche Webhook-Limit Ihrer Organisation angerechnet, das je nach Ihrem Zoho Books-Tarif variiert.

Sichern Sie Ihre Webhooks

Die Sicherung Ihrer Webhooks kann helfen, zu überprüfen, dass die Webhooks von Zoho Books gesendet wurden. Dazu müssen Sie Ihren Server so einrichten, dass er auf Webhooks von Zoho Books hört. Wenn Ihr Server einen Webhook von Zoho Books erhält, muss ein Hash-Wert basierend auf den Nutzdaten und Ihrem geheimen Token generiert werden. Überprüfen Sie anschließend, ob er mit dem Hash-Wert von Zoho Books übereinstimmt, und validieren Sie damit die Quelle des Webhooks. Dies kann eine zusätzliche Sicherheitsebene hinzufügen, indem Ihr Server in die Lage versetzt wird, Drittanbieter-Webhooks zu ignorieren, die vorgeben, von Zoho Books zu stammen.

Validieren von Webhooks

Wenn Ihr Server den Webhook erhält, muss ein Hash-Wert für die Nutzdaten auf die gleiche Weise generiert werden, wie es Zoho Books getan hat. Dies ist notwendig, um denselben Hash-Wert zu erzeugen, um den Webhook zu validieren.

Die folgenden Parameter (sofern verfügbar) werden verwendet, um den Hash-Wert zu generieren:

Abfragezeichenfolgenparameter.
Standard-Nutzdaten oder angepasste rohe JSON-Nutzdaten.
x-www-form-urlencoded-Nutzdaten (Schlüssel-Wert-Paare).

Konstruieren Sie eine Zeichenfolge, indem Sie die Schlüssel-Wert-Paare der Nutzdaten in alphabetischer Reihenfolge sortieren. Die Paare müssen in alphabetischer Reihenfolge in Bezug auf ihre Schlüssel sortiert werden.

Hinweis

Wenn Ihr Webhook Abfragezeichenfolgenparameter enthält, stellen Sie sicher, dass diese Schlüssel-Wert-Paare zusammen mit den Schlüssel-Wert-Paaren der Nutzdaten sortiert werden.
Es dürfen keine Leerzeichen zwischen den Schlüssel-Wert-Paaren vorhanden sein.

Sobald Sie die Schlüssel-Wert-Paare sortiert und die Zeichenfolge erstellt haben, fügen Sie das rohe JSON am Ende der Zeichenfolge an.

Beispiele

1. Standard-Nutzdaten

Schlüssel-Wert-Paare der Abfragezeichenfolgenparameter:

subscription\_id=90343, name=basic

Standard-Nutzdaten/rohes JSON:

{"created\_date":"2019-03-06","event\_id":"5675"}

Die erstellte Zeichenfolge wäre:

namebasicsubscription\_id90343{"created\_date":"2019-03-06","event\_id":"5675"}

2. x-www-form-urlencoded

Schlüssel-Wert-Paare der Abfragezeichenfolgenparameter:

customer\_name=Brandon, status=active

Schlüssel-Wert-Paare der x-www-form-urlencoded-Nutzdaten:

addon\_description=Monthly addon, quantity=1

Die erstellte Zeichenfolge wäre:

addon\_descriptionMonthly addoncustomer\_nameBrandonquantity1statusactive

Pro-Tipp

Wenn Ihre Nutzdaten im x-www-form-urlencoded-Format vorliegen, muss die gesamte Zeichenfolge dekodiert werden, bevor der Hash-Wert generiert wird.
Wenn eines der Schlüssel-Wert-Paare Leerzeichen enthält, müssen die Leerzeichen ebenfalls in die erstellte Zeichenfolge aufgenommen werden.

Der Hash-Wert kann berechnet werden, indem der HMAC-SHA256-Algorithmus auf diese Zeichenfolge angewendet wird, zusammen mit dem geheimen Token, das in Zoho Books verwendet wurde.

Sie können den Webhook dann validieren, indem Sie überprüfen, ob der von Ihrer Seite berechnete Hash-Wert mit dem im Header (X-Zoho-Webhook-Signature) des Webhooks von Zoho Books übereinstimmt.

Sie können Ihre Webhook-Signatur mit den folgenden Programmiersprachen überprüfen:

JavaScript:

const crypto = require('crypto');

function verifyWebhook(queryParams, bodyParams, signature, secretKey) {
  try {
    const constructedString = constructString(queryParams, bodyParams);

    const hmac = crypto.createHmac('sha256', secretKey);
    hmac.update(constructedString);

    const calculatedSignature = hmac.digest('base64');

    return calculatedSignature === signature;
  } catch (error) {
    console.error(error);
    return false;
  }
}

function constructString(queryParams, bodyParams) {
  // Merge and sort keys
  const allParams = { ...queryParams, ...bodyParams };
  const sortedKeys = Object.keys(allParams).sort();

  let result = '';
  for (const key of sortedKeys) {
    result += key + allParams[key];
  }

  return result;
}

Java:

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Map;
import java.util.TreeMap;
import java.util.Base64;

public class Hmacverify {

    public static boolean verifyWebhook(Map<String, String> queryParams, Map<String, String> bodyParams, String signature, String secretKey) {
        try {
            String constructedString = constructString(queryParams, bodyParams);

            Mac sha256HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
            sha256HMAC.init(secretKeySpec);

            byte[] hash = sha256HMAC.doFinal(constructedString.getBytes());
            String calculatedSignature = Base64.getEncoder().encodeToString(hash);

            return calculatedSignature.equals(signature);
        } catch (Exception e) {
            e.printStackTrace();
            return false;
        }
    }

    private static String constructString(Map<String, String> queryParams, Map<String, String> bodyParams) {
        StringBuilder result = new StringBuilder();


        TreeMap<String, String> sortedParams = new TreeMap<>(queryParams);
        sortedParams.putAll(bodyParams);

        for (Map.Entry<String, String> entry : sortedParams.entrySet()) {
            result.append(entry.getKey()).append(entry.getValue());
        }

        return result.toString();
    }
}

Python:

import hmac
import hashlib
import base64

def verifyWebhook(queryParams, bodyParams, signature, secretKey):
    constructedString = constructString(queryParams, bodyParams)

    calculatedSignature = base64.b64encode(hmac.new(secretKey.encode(), constructedString.encode(), hashlib.sha256).digest()).decode()

    return calculatedSignature == signature

def constructString(queryParams, bodyParams):
    # Merge and sort query and body parameters
    allParams = {**queryParams, **bodyParams}
    sortedParams = sorted(allParams.items())

    result = ''.join([key + value for key, value in sortedParams])

    return result

# Example usage
queryParams = {'subscription_id': '90343', 'name': 'basic'}
bodyParams = {'created_date': '2019-03-06', 'event_id': '5675'}
signature = 'provided-signature'
secretKey = 'your-secret-key'

verifyWebhook(queryParams, bodyParams, signature, secretKey)

Konfigurieren von SMS-Gateways

Sie können Webhooks einrichten, um Nachrichtenbenachrichtigungen über SMS-Gateways zu senden und zu empfangen. Alles, was Sie tun müssen, ist, die SMS-Gateways mit der URL zu konfigurieren und die unten angegebenen Schritte zu befolgen.

Bulk SMS

Bulk SMS ist ein beliebtes SMS-Gateway und ist mit über 800 Mobilfunkanbietern weltweit kompatibel.

URL: https://bulksms.vsms.net/eapi/submission/send_sms/2/2.0?username=%username%&password=%password%&msisdn=${CONTACT.CONTACT_MOBILE_PHONE}&message=%message_content%

Um die URL für Bulk SMS zu konfigurieren:

Klicken Sie auf das Zahnrad-Symbol oben rechts und wählen Sie Automatisierung.
Navigieren Sie zum Tab Webhooks und klicken Sie auf + Neuer Webhook.
Kopieren Sie die obige URL in das Feld URL zur Benachrichtigung.
Ersetzen Sie die Platzhalter %username% und %password% in der URL durch den Benutzernamen und das Passwort Ihres Bulk SMS-Kontos.
Geben Sie Ihre Nachricht am Ende der URL ein, das heißt nach “message=”.
Ersetzen Sie alle Leerzeichen in Ihrem Nachrichteninhalt durch %20 und alle Kommas durch %2C.

Hinweis: Wenn es andere Satzzeichen in Ihrem Nachrichteninhalt gibt, können Sie auf dieser Website überprüfen, wie Sie diese mit Modifikatoren ersetzen können. Stellen Sie jedoch sicher, dass Sie keine Satzzeichen ersetzen, die für die Syntax der Nachricht wesentlich sind.

Nachdem Sie Ihre Nachricht mit %20 für Leerzeichen und %2C für Kommas formatiert haben, sollte sie so aussehen:

URL: https://bulksms.vsms.net/eapi/submission/send_sms/2/2.0?username=%username%&password=%password%&msisdn=${CONTACT.CONTACT_MOBILE_PHONE}&message=Hello%20${CONTACT.CONTACT_NAME}.Thank%20you%20for%20the%20purchase%20of%20${INVOICE.INVOICE_TOTAL}

Ähnlich können andere SMS-Gateways konfiguriert werden, wobei nur die URL unterschiedlich ist.

SMS-Magic

SMS-Gateways wie SMS-Magic erfordern, dass Sie zusätzliche Entitätsparameter eingeben, um den Webhook zu konfigurieren.

Um SMS-Magic zu konfigurieren:

Geben Sie die URL https://sms-magic.in/smapi/post in das Feld URL zur Benachrichtigung ein.
Klicken Sie auf + Entitätsparameter hinzufügen.
Geben Sie den folgenden Text in das Parameterfeld ein:

<?xml version="1.0"?>
<m:Library xmlns:m="http://screen-magic.com" xmlns="http://www.defns.com">
<userid>**User_ID**</userid>
<senderid>**%Sender_ID**</senderid>
<accountid>**%Account_ID**</accountid>
<hashkey>**%hashkey%**</hashkey>
<message mobilenumber="${CONTACT.CONTACT_MOBILE_PHONE}" >
<![CDATA[${INVOICE.INVOICE_TOTAL}]]>
</message>
</m:Library>

Ersetzen Sie die Platzhalter in der URL durch die Benutzer-ID, Sender-ID und Konto-ID Ihres SMS-Magic-Kontos. Der Hashkey bezieht sich auf einen standardmäßig gehashten md5-Wert eines Strings, der eine Verkettung Ihrer Benutzer-ID, Ihres Passworts, Ihrer Konto-ID und Ihrer Sender-ID ist.

Hinweis: Um den gehashten md5-Wert zu generieren, können Sie diese Seite besuchen.

Text Local

Text Local erfordert einen Entitätsparameter und einen benutzerdefinierten Parameter, um zu funktionieren.

Um Text Local zu konfigurieren:

Geben Sie die URL http://api.textlocal.in/send/ in das Feld URL zur Benachrichtigung ein.
Klicken Sie auf + Benutzerdefinierten Parameter hinzufügen.
Fügen Sie die Parameter sender und apikey hinzu und ersetzen Sie die Platzhalter in der URL durch die entsprechenden Informationen von Text Local.
Klicken Sie auf + Entitätsparameter hinzufügen.
Geben Sie einen Namen für den Parameter ein und wählen Sie die erforderlichen Bedingungen aus dem Dropdown-Menü aus. Beispiel: numbers = ${CONTACT.CONTACT_MOBILE_PHONE}
Aktivieren Sie das Kontrollkästchen Benutzerdefinierte Parameter hinzufügen und geben Sie die zu sendende Nachricht zusammen mit allen erforderlichen Platzhaltern ein.
Klicken Sie auf Speichern.

Webhooks bearbeiten

Wenn Sie die Details eines Webhooks aktualisieren möchten, können Sie ihn bearbeiten. So geht’s:

Gehen Sie zu Einstellungen in der oberen rechten Ecke der Seite.
Wählen Sie Workflow-Aktionen unter Automatisierung.
Wählen Sie im Bereich Workflow-Aktionen Webhooks.
Fahren Sie mit der Maus über den Webhook, den Sie bearbeiten möchten, klicken Sie auf das Dropdown-Menü rechts und wählen Sie Bearbeiten.
Nehmen Sie die erforderlichen Änderungen vor und klicken Sie auf Speichern.

Webhooks filtern

Um die Webhook-Liste zu filtern, befolgen Sie diese Schritte:

Gehen Sie zu Einstellungen in der oberen rechten Ecke der Seite.
Wählen Sie Workflow-Aktionen unter Automatisierung.
Wählen Sie im Bereich Workflow-Aktionen Webhooks.
Wählen Sie unter Modul ein Modul aus dem Dropdown-Menü aus, für das der Webhook erstellt wurde.

Basierend auf Ihrer Auswahl wird der entsprechende Webhook als Liste angezeigt.