Webhooks

Ein Webhook ist ein von einem Partner erstellter HTTPS-Callback, der angibt, wie der Agent auf Nachrichten und Ereignisse reagieren soll. Nachdem Sie den Webhook konfiguriert haben, können Sie Nachrichten und Ereignisse empfangen.

Partner-Webhooks und Agent-Webhooks

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

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

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

Agent-Webhook konfigurieren

Sie empfangen Nachrichten, die an Ihren Agent in Ihrem Partner-Webhook gesendet werden. Wenn Nachrichten für einen bestimmten Agent stattdessen bei einem anderen Webhook ankommen sollen, legen Sie einen Agent-Webhook fest.

  1. Öffnen Sie die Business Communications Developer Console und melden Sie sich mit Ihrem RBM-Partner-Google-Konto an.
  2. Klicken Sie auf den Agent.
  3. Klicken Sie auf Integrations (Integrationen).
  4. Klicken Sie für Webhook auf Konfigurieren.
  5. Geben Sie unter Webhook-Endpunkt-URL die Webhook-URL ein, die mit „https://“ beginnt.
  6. Notieren Sie sich den clientToken-Wert. Sie benötigen sie, um zu überprüfen, ob Nachrichten von Google stammen.

  7. Konfigurieren Sie den Webhook so, dass er eine POST-Anfrage mit dem angegebenen Parameter clientToken akzeptiert und eine 200 OK-Antwort mit dem Nur-Text-Wert des Parameters secret als Antworttext sendet.

    Beispiel: Ihr Webhook erhält eine POST-Anfrage mit dem folgenden Textinhalt:

    {
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}

    Der Webhook sollte den Wert clientToken bestätigen. Wenn clientToken korrekt ist, sollte er eine 200 OK-Antwort mit 1234567890 als Antworttext zurückgeben:

    // clientToken from Configure
const myClientToken = "SJENCPGJESMGUFPY";

// Example endpoint
app.post("/rbm-webhook", (req, res) => {
  const msg = req.body;
  if (msg.clientToken === myClientToken) {
      res.status(200).send(msg.secret);
      return;
  }
  res.send(400);
});

  8. Klicken Sie in der Developer Console auf Bestätigen. Sobald RBM den Webhook verifiziert hat, wird das Dialogfeld geschlossen.

Eingehende Nachrichten überprüfen

Da Webhooks Nachrichten von beliebigen Absendern empfangen können, sollten Sie vor der Verarbeitung des Nachrichteninhalts prüfen, ob Google eingehende Nachrichten gesendet hat.

So überprüfen Sie, ob Google eine Nachricht gesendet hat, die Sie erhalten haben:

  1. Extrahieren Sie den X-Goog-Signature-Header der Nachricht. Dies ist eine base64-codierte, gehashte Kopie der Nutzlast des Nachrichtentexts.
  2. Mit Base64 decodieren Sie die RBM-Nutzlast im message.body-Element der Anfrage.
  3. Verwenden Sie das Clienttoken des Webhooks, das Sie beim Einrichten des Webhooks angegeben haben, als Schlüssel, erstellen Sie einen SHA512-HMAC der Byte der base64-decodierten Nachrichtennutzlast und codieren Sie das Ergebnis mit base64.
  4. Vergleichen Sie den Hash X-Goog-Signature mit dem von Ihnen erstellten Hash.
    • Wenn die Hashwerte übereinstimmen, haben Sie bestätigt, dass die Nachricht von Google gesendet wurde.

    • Wenn die Hashwerte nicht übereinstimmen, prüfen Sie Ihren Hash-Vorgang bei einer als fehlerfrei bekannten Nachricht.

      Wenn Ihr Hash-Prozess korrekt funktioniert und Sie eine Nachricht erhalten, die Ihrer Meinung nach in betrügerischer Absicht an Sie gesendet wurde, wenden Sie sich an uns.

Node.js

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

    if (headerHash === genHash) {
      let userEvent = JSON.parse(userEventString);

      console.log('userEventString: ' + userEventString);
      handleMessage(userEvent);
    } else {
      console.log('hash mismatch - ignoring message');
    }
  }

  res.sendStatus(200);

Nächste Schritte

Nachdem Sie den Webhook konfiguriert haben, kann der Agent von Ihren Testgeräten Nachrichten empfangen. Senden Sie eine Nachricht, um die Einrichtung zu validieren.