Webhooks

Ein Webhook ist eine vom Partner angegebene URL, an die die RCS for Business-Plattform Nachrichten und Ereignissesendet. Diese URL fungiert als Endpunkt, der HTTPS-POST-Anfragen mit Daten zu den Ereignissen empfängt. Das bedeutet, dass Daten sicher über HTTPS an Ihre Anwendung gesendet werden.

Eine Webhook-URL könnte so aussehen: https://[your company name].com/api/rbm-events. Nachdem Sie Ihren Webhook konfiguriert haben, können Sie Nachrichten und Ereignisse empfangen.

Warnung: RCS for Business stellt Nachrichten für einen Partner in eine Warteschlange. Wenn der Webhook eines Agenten fehlschlägt (kein 200 zurückgibt), kann sich das auf die Zustellung der Webhooks aller anderen Agenten im selben Partnerkonto auswirken. Weitere Informationen finden Sie unter Auswirkungen von Webhooks auf Agent-Ebene.

Partner-Webhooks und Agent-Webhooks

Sie können Ihren Webhook entweder auf Partner- oder auf Agent-Ebene konfigurieren.

• Ihr Partner-Webhook gilt für alle Agenten, die Sie verwalten. Wenn sich Ihre Agenten ähnlich verhalten oder Sie nur einen Agenten haben, verwenden Sie den Partner-Webhook.
• Agent-Webhooks gelten für einzelne Agenten. Wenn Sie mehrere Agenten mit unterschiedlichem Verhalten verwenden, können Sie für jeden Agenten einen anderen Webhook festlegen.

Wenn Sie sowohl einen Partner-Webhook als auch einen Agent-Webhook konfiguriert haben, hat der Agent-Webhook für den jeweiligen Agenten Vorrang. Der Partner-Webhook gilt für alle Agenten, die keinen eigenen Webhook haben.

Agent-Webhook konfigurieren

**Hinweis**: Informationen zum Erstellen einer Webhook-Integration mit der RBM Management API finden Sie in der Dokumentation Webhook-Integration erstellen.

Sie erhalten Nachrichten, die an Ihren Agenten gesendet werden, an Ihrem Partner-Webhook. Wenn Nachrichten für einen bestimmten Agenten stattdessen an einen anderen Webhook gesendet werden sollen, legen Sie einen Agent-Webhook fest.

1. Öffnen Sie die RCS for Business Developer Console und melden Sie sich mit Ihrem Google-Konto für RCS for Business-Partner an.
2. Klicken Sie auf Ihren Agenten.
3. Klicken Sie auf Integrationen.

4. Klicken Sie im Bereich Webhook auf Konfigurieren.

   1. Geben Sie unter Webhook-Endpunkt Ihre Webhook-URL ein, die mit "https://" beginnt.
   2. Geben Sie unter Client-Token den Wert für clientToken an. Sie benötigen ihn, um zu überprüfen ob die Nachrichten, die Sie erhalten, von Google stammen.
   Hinweis: Das aktuelle Client-Token kann aus Sicherheitsgründen nicht angezeigt werden. Wenn Sie ein neues Client-Token erstellen möchten, geben Sie einen Wert in das entsprechende Feld ein oder klicken Sie auf Aktualisieren , um einen zufälligen Wert zu generieren.

5. Richten Sie Ihren Webhook so ein, dass er POST-Anfragen mit einer JSON-Nutzlast akzeptiert, die die Parameter clientToken und secret enthält.

   {
     "clientToken":"YOURCLIENTTOKEN",
     "secret":"YOURSECRET"
   }
   

   Um die Anfrage zu validieren, muss Ihr Endpunkt den HTTP-Statuscode 200 OK mit dem Rohstringwert des Parameters secret im Antworttext zurückgeben.

   Beispielkonfiguration für Webhooks

   Wenn Ihr Webhook beispielsweise eine POST Anfrage mit folgendem Text empfängt:

     {
     "clientToken":"YOURCLIENTTOKEN",
     "secret":"YOURSECRET"
     }
     

   Dann sollte Ihr Webhook den Wert clientToken bestätigen und, falls clientToken korrekt ist, eine 200 OK Antwort mit YOURSECRET als Antworttext zurückgeben:

     // clientToken from Configure
     const myClientToken = "YOURCLIENTTOKEN";
   
     // Example endpoint
     app.post("/rbm-webhook", (req, res) => {
       // Use the X-Goog-Webhook-Type header to route requests
       const webhookType = req.header('X-Goog-Webhook-Type');
   
       if (webhookType === 'verification') {
         const msg = req.body;
         if (msg.clientToken === myClientToken) {
             res.status(200).send(msg.secret);
             return;
         }
       }
       res.send(400);
       // Handle other webhook types
     });
     

6. Klicken Sie in der Developer Console auf Bestätigen. Nachdem Sie auf Bestätigen geklickt haben, sendet Google eine POST Anfrage an Ihren Webhook. Die Anfrage enthält die Parameter clientToken und secret. Wenn RCS for Business Ihren Webhook bestätigt, wird das Dialogfeld geschlossen.

Anfragetypen identifizieren

Verwenden Sie den Header X-Goog-Webhook-Type, um den Anfragetyp für alle Anfragen zu identifizieren, die an Ihren Webhook gesendet werden.

Der Header kann die folgenden Werte haben:

• verification: Wird für den ersten Endpunktbestätigungsprozess verwendet.
• message_callback: Wird für nachrichtenbezogene Ereignisse verwendet, z. B. Benachrichtigungen über das Tippen oder die Zustellung und eingehende Nachrichten von Nutzern.
• agent_callback: Wird für agentspezifische Verwaltungsereignisse verwendet, z. B. Änderungen des Startstatus des Agenten.

Eingehende Nachrichten bestätigen

Da Webhooks Nachrichten von jedem Absender empfangen können, sollten Sie bestätigen, dass Google eingehende Nachrichten gesendet hat, bevor Sie den Nachrichtentext verarbeiten.

So bestätigen Sie, dass Google eine Nachricht gesendet hat, die Sie erhalten haben:

1. Extrahieren Sie den Header X-Goog-Signature der Nachricht. Dies ist eine gehashte, base64-codierte Kopie der Nachrichtentext-Nutzlast.
2. Decodieren Sie die RCS for Business-Nutzlast im Element message.body der Anfrage mit Base64.
3. Erstellen Sie mit dem Client-Token Ihres Webhooks (das Sie beim Einrichten Ihres Webhooks angegeben haben) als Schlüssel einen SHA512-HMAC der Byte der base64-decodierten Nachrichtennutzlast und codieren Sie das Ergebnis mit Base64.
4. Vergleichen Sie den X-Goog-Signature-Hash mit dem von Ihnen erstellten Hash.
   • Wenn die Hashes übereinstimmen, haben Sie bestätigt, dass Google die Nachricht gesendet hat.

   • Wenn die Hashes nicht übereinstimmen, prüfen Sie den Hashing-Prozess für eine bekannte, korrekte Nachricht.

     Wenn Ihr Hashing-Prozess korrekt funktioniert und Sie eine Nachricht erhalten, die Ihrer Meinung nach betrügerisch an Sie gesendet wurde, kontaktieren Sie uns.

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    const headerHash = req.header('X-Goog-Signature');
    const userEventString = Buffer.from(requestBody.message.data, 'base64');
    const hmac = crypto.createHmac('sha512', myClientToken);
    const genHash = hmac.update(userEventString).digest('base64');

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);
  

Nachrichtenverarbeitung

Alles andere als 200 OK von einem Webhook zurückzugeben, gilt als Zustellungsfehler.

Entwickler müssen beachten, dass das Senden von Nachrichten mit hoher Geschwindigkeit Webhook-Benachrichtigungen mit hoher Geschwindigkeit generiert. Sie müssen ihren Code so gestalten, dass er Benachrichtigungen mit der erwarteten Geschwindigkeit verarbeiten kann. Entwickler müssen Situationen berücksichtigen, die zu Fehlerantworten führen können, einschließlich 500-Antworten von ihrem Webcontainer, Zeitüberschreitungen oder Upstream-Fehlern. Beachten Sie Folgendes:

• Prüfen Sie, ob Ihre DDoS-Schutzmaßnahmen so konfiguriert sind, dass sie die erwartete Geschwindigkeit von Webhook-Benachrichtigungen verarbeiten können.
• Prüfen Sie, ob Ressourcen wie Datenbankverbindungspools nicht erschöpft sind und Zeitüberschreitungen oder 500-Antworten erzeugen.

Entwickler sollten ihre Systeme so gestalten, dass die Verarbeitung von RBM-Ereignissen asynchron erfolgt und der Webhook nicht daran gehindert wird, 200 OK zurückzugeben.

Es ist wichtig, das RBM-Ereignis nicht im Webhook selbst zu verarbeiten. Jeder Fehler oder jede Verzögerung bei der Verarbeitung kann sich auf den Rückgabecode des Webhooks auswirken:

Verhalten bei Zustellungsfehlern

Wenn Ihr Webhook einen anderen Status als 200 OK zurückgibt, verwendet die RCS for Business-Plattform einen Backoff- und Wiederholungsmechanismus, um die Daten noch einmal zuzustellen. Das bedeutet, dass das System die Verzögerung zwischen den einzelnen Zustellungsversuchen schrittweise erhöht und schließlich eine maximale Häufigkeit von einem Wiederholungsversuch alle 10 Minuten für jede ausstehende Nachricht erreicht. Der Wiederholungszyklus wird sieben Tage lang fortgesetzt. Danach wird die Nachricht endgültig gelöscht.

Auswirkungen von Webhooks auf Agent-Ebene

RCS for Business stellt Nachrichten für einen Partner in eine Warteschlange. Alle Agenten unter einem einzelnen Partnerkonto verwenden dieselbe Warteschlange. Aus diesem Grund kann ein Fehler in einem Webhook die gesamte Warteschlange blockieren und verhindern, dass Nutzerereignisse für alle Agenten den Partner erreichen.

Mehrere unbestätigte Nachrichten können zu einem massiven Anstieg der Wiederholungsereignisse führen. Wenn ein Agent beispielsweise 1.600 Zustellungsbestätigungen nicht bestätigt und die Wiederholungshäufigkeit das 10-Minuten-Limit erreicht, können etwa 230.000 potenzielle Fehler pro Tag auftreten:

1.600 Nachrichten × 6 Wiederholungsversuche pro Stunde × 24 Stunden pro Tag = etwa 230.000 Fehler pro Tag

Dieses Volumen an Wiederholungsversuchen kann die gemeinsame Pub/Sub-Warteschlange blockieren und zu erheblichen Verzögerungen beim Empfang von Nutzerereignissen für alle Kampagnen eines Partners führen.

Best Practices

Folgen Sie diesen Best Practices, um die Zuverlässigkeit Ihres Produktionsdatenverkehrs zu gewährleisten und Warteschlangenblockierungen zu vermeiden:

• Sofort 200 OK zurückgeben: Der Webhook sollte die Nachricht empfangen, in einer lokalen Warteschlange speichern und innerhalb von fünf Sekunden eine 200 OK Antwort zurückgeben.
• Verarbeitung entkoppeln: Verwenden Sie separate Hintergrundprozesse, um die Nachrichtenlogik aus der lokalen Warteschlange zu verarbeiten.
• Testagenten überwachen: Behandeln Sie Entwicklungsagenten wie Produktionsagenten, da sie bei einem Fehler auch die gemeinsame Partnerwarteschlange blockieren können.
• Separate Konten für Tests: Verwenden Sie vorzugsweise ein Entwicklerkonto für Produktionsagenten und ein separates Entwicklerkonto für Testagenten.
• Google-Traffic bestätigen: Verwenden Sie Reverse-DNS oder den X-Goog-Signature Header anstelle einer festen Zulassungsliste für IP-Adressen, da Google dynamische Anycast-IP-Adressen verwendet. Weitere Informationen zur manuellen Bestätigung und zur Identifizierung von Google-IP-Bereichen finden Sie in der Dokumentation Google-Anfragen bestätigen und insbesondere in den JSON-Dateien für Fetcher, die vom Nutzer ausgelöst wurden und Fetcher, die von Google ausgelöst wurden.

Nächste Schritte

Nachdem Sie Ihren Webhook konfiguriert haben, kann Ihr Agent Nachrichten von Ihren Testgerätenempfangen. Senden Sie eine Nachricht um Ihre Einrichtung zu bestätigen.