Webhook

Un webhook è un URL specificato dal partner in cui la piattaforma RBM pubblica messaggi ed eventi. Questo URL funge da endpoint che riceve richieste POST HTTPS contenenti dati sugli eventi. Ciò significa che i dati vengono inviati alla tua applicazione in modo sicuro tramite HTTPS.

Un URL webhook potrebbe avere un aspetto simile a questo: https://[your company name].com/api/rbm-events. Una volta configurato il webhook, puoi iniziare a ricevere messaggi ed eventi.

Webhook partner e webhook agente

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

  • Il webhook partner si applica a ogni agente che gestisci. Se i tuoi agenti hanno un comportamento simile o se hai un solo agente, utilizza il webhook 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 sia un webhook agente, il webhook agente ha la precedenza sul suo agente specifico, mentre il webhook partner si applica a tutti gli agenti che non hanno un proprio webhook.

Configura un webhook dell'agente

Ricevi i messaggi inviati al tuo agente nel webhook del partner. Se vuoi che i messaggi per un agente specifico arrivino a un webhook diverso, imposta un webhook agente.

  1. Apri Business Communications Developer Console e accedi con il tuo Account Google 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 valore di clientToken. Ti serve per verificare che i messaggi che ricevi provengano da Google.

  7. Configura il webhook in modo che accetti una richiesta POST con il parametro clientToken specificato e invii una risposta 200 OK con il valore di 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. In Developer Console, fai clic su Verifica. Quando RBM verifica il webhook, la finestra di dialogo si chiude.

Verificare i messaggi in arrivo

Poiché i webhook possono ricevere messaggi da qualsiasi mittente, devi verificare che Google abbia inviato i messaggi in arrivo prima di elaborarne il contenuto.

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 base64 del payload del corpo del messaggio.
  2. Decodifica in base64 il payload RBM nell'elemento message.body della richiesta.
  3. Utilizzando il token client del webhook (che hai specificato durante la configurazione del webhook) come chiave, crea un HMAC SHA512 dei byte del payload del messaggio con codifica Base64 e codifica Base64 il risultato.
  4. Confronta l'hash X-Goog-Signature con l'hash che hai creato.
    • Se gli hash corrispondono, hai la conferma che il messaggio è stato inviato da Google.

    • Se gli hash non corrispondono, controlla la procedura di hashing su un messaggio di cui è noto il corretto funzionamento.

      Se la procedura di hashing funziona correttamente e ricevi un messaggio che ritieni ti sia 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);

Gestione dei messaggi

La restituzione di un valore diverso da 200 OK da un webhook viene considerata un errore di consegna.

Gli sviluppatori devono tenere presente che l'invio di messaggi a velocità elevate genererà notifiche webhook a velocità elevate e devono progettare il codice in modo da gestire le notifiche alla velocità prevista. È importante che gli sviluppatori prendano in considerazione le situazioni che potrebbero causare risposte di errore, incluse le risposte 500 dal contenitore web, i timeout o gli errori upstream. Aspetti da considerare:

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

Gli sviluppatori devono progettare i propri sistemi in modo che l'elaborazione degli eventi RBM avvenga in modo asincrono e non impedisca al webhook di restituire 200 OK.

Elaborazione asincrona dei webhook

È importante non elaborare l'evento RBM all'interno del webhook stesso. Qualsiasi errore o ritardo durante l'elaborazione può influire sul codice restituito del webhook:

Elaborazione sincrona dei webhook

Comportamento in caso di mancata pubblicazione

RBM utilizza un meccanismo di backoff e ripetizione quando riceve una risposta diversa da 200 OK da una chiamata webhook. RBM aumenterà il tempo di attesa tra i tentativi fino a un massimo di 600 secondi. I tentativi verranno ripetuti per 7 giorni, dopodiché il messaggio verrà eliminato.

Implicazioni dei webhook a livello di agente

RBM accoda 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, man mano che i messaggi non riusciti vengono messi in coda per il nuovo tentativo, i tassi di recapito complessivi diminuiranno e altri agenti ne risentiranno.

È importante che gli sviluppatori comprendano questo modello e codifichino di conseguenza, accettando i messaggi e mettendoli in coda per l'elaborazione per ridurre al minimo 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.

Avanti
Dialogflow