Webhook

Un webhook è un callback HTTPS creato da un partner che specifica in che modo l'agente deve rispondere a messaggi ed eventi. Dopo aver configurato il webhook, puoi iniziare a ricevere messaggi ed eventi.

Webhook partner e agente

Puoi configurare il webhook a livello di partner o di agente.

  • Il webhook partner si applica a tutti gli agenti che gestisci. Se i tuoi agenti hanno un comportamento simile o hai un solo agente, utilizza il webhook partner.
  • I webhook degli agenti si applicano ai singoli agenti. Se utilizzi più agenti con un comportamento distinto, puoi impostare un webhook diverso per ogni agente.

Se hai configurato sia un webhook del partner sia un webhook dell'agente, il webhook dell'agente ha la precedenza sul suo agente specifico, mentre il webhook del partner si applica a tutti gli agenti che non dispongono di un proprio webhook.

Configura un webhook agente

Ricevi i messaggi inviati all'agente nel webhook partner. Se vuoi che i messaggi di un agente specifico arrivino a un webhook diverso, imposta un webhook dell'agente.

  1. Apri la Console per gli sviluppatori di Business Communications e accedi con il tuo Account Google del partner RBM.
  2. Fai clic sull'agente.
  3. Fai clic su Integrations (Integrazioni).
  4. Per Webhook, fai clic su Configura.
  5. In URL endpoint webhook, inserisci l'URL webhook che inizia con "https://".
  6. Prendi nota del tuo valore di clientToken. È necessario per verificare che i messaggi ricevuti provengano da Google.

  7. Configura il webhook per accettare una richiesta POST con il parametro clientToken specificato e invia una risposta 200 OK con il valore in testo normale del parametro secret come corpo della risposta.

    Ad esempio, se il webhook riceve una richiesta POST con i seguenti contenuti del corpo

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

    il webhook deve confermare il valore clientToken e, se clientToken è corretto, restituire una risposta 200 OK con 1234567890 come corpo della risposta:

    // 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. Nella Developer Console, fai clic su Verifica. Quando RBM verifica il webhook, la finestra di dialogo si chiude.

Verifica i messaggi in arrivo

Poiché i webhook possono ricevere messaggi da qualsiasi mittente, devi verificare che Google abbia inviato messaggi in arrivo prima di elaborare i contenuti dei messaggi.

Per verificare che Google abbia inviato un messaggio che hai ricevuto, segui questi passaggi:

  1. Estrai l'intestazione X-Goog-Signature del messaggio. Questa è una copia sottoposta ad hashing e codificata in Base64 del payload del corpo del messaggio.
  2. Decodifica in base 64 il payload RBM nell'elemento message.body della richiesta.
  3. Utilizzando il token client del webhook (specificato quando hai configurato il webhook) come chiave, crea un HMAC SHA512 dei byte del payload dei messaggi decodificato in base-64 e codifica il risultato in base64.
  4. Confronta l'hash X-Goog-Signature con l'hash che hai creato.
    • Se gli hash corrispondono, significa che Google ha inviato il messaggio.

    • Se gli hash non corrispondono, controlla la procedura di hashing su un messaggio noto.

      Se la procedura di hashing funziona correttamente e ricevi un messaggio che a tuo parere ti è stato inviato in modo fraudolento, contattaci.

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

Passaggi successivi

Una volta configurato il webhook, l'agente può ricevere messaggi dai dispositivi di test. Invia un messaggio per convalidare la configurazione.