Webhook

Un webhook è un callback HTTPS creato dal partner che specifica come deve rispondere l'agente a messaggi ed eventi. Una volta configurato l'webhook, puoi iniziare a ricevere messaggi e eventi.

Webhook partner e webhook agente

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

  • L'webhook del partner si applica a tutti gli agenti che gestisci. Se i tuoi agenti hanno un comportamento simile o se hai un solo agente, utilizza il webhook del partner.
  • I webhook dell'agente si applicano ai singoli agenti. Se gestisci più agenti con comportamenti distinti, puoi impostare un webhook diverso per ogni agente.

Se hai configurato sia un webhook partner che un webhook 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 hanno un proprio webhook.

Configurare un webhook dell'agente

Riceverai i messaggi inviati all'agente nell'webhook del partner. Se vuoi invece che i messaggi per un agente specifico arrivino a un webhook diverso, imposta un webhook agente.

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

  7. Configura il tuo webhook in modo che accetti una richiesta POST con il parametro clientToken specificato e invii una risposta 200 OK con il valore in testo normale del parametro secret come corpo della risposta.

    Ad esempio, se il tuo webhook riceve una richiesta POST con il seguente testo del corpo

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

    in questo caso, l'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. In Developers Console, fai clic su Verifica. Quando RBM verifica il webhook, la finestra di dialogo si chiude.

Verificare i messaggi in arrivo

Poiché gli webhook possono ricevere messaggi da qualsiasi mittente, devi verificare che Google abbia inviato i 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. Si tratta di una copia con hash e codifica in base64 del payload del corpo del messaggio.
  2. Decodifica il payload RBM in base 64 nell'elemento message.body della richiesta.
  3. Utilizzando il token client del webhook (che hai specificato al momento della configurazione del webhook) come chiave, crea un HMAC SHA512 dei byte del payload dei messaggi decodificato in Base64 e codifica il risultato in base64.
  4. Confronta l'hash X-Goog-Signature con quello che hai creato.
    • Se gli hash corrispondono, hai confermato che il messaggio è stato inviato da Google.

    • 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 ritieni ti sia stato inviato fraudolentemente, 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);

Gestione dei messaggi

Il ritorno di un valore diverso da 200 OK da un webhook è considerato un errore di invio.

Gli sviluppatori devono tenere presente che l'invio di messaggi con frequenze elevate genererà notifiche webhook a tariffe elevate e devono progettare il proprio codice per garantire che possano utilizzare le notifiche con la frequenza prevista. È importante che gli sviluppatori tengano conto delle situazioni che potrebbero causare risposte di errore, tra cui le risposte 500 del contenitore web, i timeout o gli errori a monte. Ecco alcuni aspetti da considerare:

  • Assicurati che le protezioni DDoS siano configurate per gestire la frequenza prevista delle notifiche webhook.
  • Assicurati che le risorse come i pool di connessioni al database non si esauriscano e producano timeout o risposte 500.

Comportamento in caso di errore di recapito

RBM utilizza un meccanismo di backoff e di nuovo tentativo quando riceve una risposta diversa da 200 OK da una chiamata webhook. RBM aumenta il tempo di attesa tra un nuovo tentativo e l'altro fino a un massimo di 600 secondi. I tentativi continueranno per 7 giorni, dopodiché il messaggio verrà eliminato.

Implicazioni dei webhook a livello di agente

RBM mette in coda i messaggi per un partner in una coda. Se un partner utilizza webhook a livello di agente, è importante tenere presente che l'errore di un webhook influirà sulla distribuzione ad altri webhook. I webhook appartenenti ad altri agenti verranno chiamati durante il periodo di backoff di un messaggio non riuscito. Tuttavia, se i messaggi non riusciti vengono inseriti nella coda per essere riprovati, le percentuali di recapito complessive diminuiranno e ne risentiranno gli altri agenti.

È importante che gli sviluppatori comprendano questo modello e lo codifichino di conseguenza, accettando i messaggi e mettendoli in coda per l'elaborazione per quanto possibile, in modo da minimizzare la possibilità di restituire un errore.

Passaggi successivi

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