Webhook

Un webhook è un URL specificato dal partner in cui la piattaforma RCS for Business 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 dell'agente.

Apri la Console per gli sviluppatori di comunicazione aziendale e accedi con il tuo Account Google partner di RCS for Business.
Fai clic sull'agente.
Fai clic su Integrations (Integrazioni).
Per Webhook, fai clic su Configura.
In URL endpoint webhook, inserisci l'URL webhook che inizia con "https://".
Prendi nota del valore di clientToken. Ti serve per verificare che i messaggi che ricevi provengano da Google.
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);
});
```
In Developer Console, fai clic su Verifica. Quando RCS for Business 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:

Estrai l'intestazione X-Goog-Signature del messaggio. Si tratta di una copia con hash e codifica base64 del payload del corpo del messaggio.
Decodifica in base 64 il payload RCS for Business nell'elemento message.body della richiesta.
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.
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 del 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 producono 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

Se il webhook restituisce un valore diverso dallo stato 200 OK, la piattaforma RCS for Business utilizza un meccanismo di backoff e ripetizione per inviare nuovamente i dati. Ciò significa che il sistema aumenta progressivamente il ritardo tra un tentativo di consegna e l'altro, fino a raggiungere una frequenza massima di un nuovo tentativo ogni 10 minuti per ogni messaggio in attesa. Il ciclo di tentativi continua per sette giorni, dopodiché il messaggio viene eliminato definitivamente.

Implicazioni dei webhook a livello di agente

RCS for Business mette in coda i messaggi per un partner in una sola coda. Tutti gli agenti di un unico account partner condividono una singola coda. Per questo motivo, un errore in un webhook può bloccare l'intera coda, impedendo agli eventi utente di tutti gli agenti di raggiungere il partner.

Diversi messaggi non riconosciuti possono causare un picco enorme di eventi di ripetizione. Ad esempio, se un agente non riconosce 1600 ricevute di consegna e la frequenza di nuovi tentativi raggiunge il limite di 10 minuti, possono essere generati circa 230.000 potenziali errori al giorno:

1600 messaggi × 6 tentativi all'ora × 24 ore al giorno = circa 230.000 errori al giorno

Questo volume di tentativi può bloccare la coda Pub/Sub condivisa e causare ritardi significativi nella ricezione degli eventi utente per tutte le campagne di un partner.

Best practice

Per garantire l'affidabilità del traffico di produzione ed evitare blocchi della coda, segui queste best practice:

Restituisci immediatamente 200 OK: il webhook deve ricevere il messaggio, memorizzarlo in una coda locale e restituire una risposta 200 OK in meno di cinque secondi.
Elaborazione disaccoppiata: utilizza worker in background separati per elaborare la logica dei messaggi dalla coda locale.
Monitora gli agenti di test: tratta gli agenti di sviluppo come agenti di produzione, perché possono anche bloccare la coda dei partner condivisa in caso di errore.
Account dedicati per i test: utilizza preferibilmente un account sviluppatore per gli agenti di produzione e un account sviluppatore dedicato per gli agenti di test.
Verifica il traffico Google: utilizza il DNS inverso o l'intestazione X-Goog-Signature anziché l'inserimento nell'allowlist di IP fissi, poiché Google utilizza IP anycast dinamici. Per maggiori informazioni sulla verifica manuale e sull'identificazione degli intervalli IP di Google, consulta la documentazione Verificare le richieste di Google e in particolare i file JSON per i fetcher attivati dall'utente e i fetcher attivati dall'utente di Google.

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