Webhook

Un webhook è un URL specificato dal partner in cui la piattaforma RCS for Business pubblica messaggi e 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. Dopo aver 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 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.

Configurare un webhook agente

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

  1. Apri la console per sviluppatori RCS for Business e accedi con il tuo account Google partner RCS for Business.
  2. Fai clic sul tuo agente.
  3. Fai clic su Integrazioni.

  4. Nella sezione Webhook, fai clic su Configura.

    1. In Endpoint webhook, inserisci l'URL webhook che inizia con "https://".
    2. In Token client, specifica il valore clientToken. Ti serve per verificare che i messaggi che ricevi provengano da Google.

  5. Configura il webhook in modo che accetti le richieste POST con un payload JSON che includa i parametri clientToken e secret.

    {
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
}

    Per convalidare la richiesta, l'endpoint deve restituire un codice di stato HTTP 200 OK con il valore della stringa non elaborata del parametro secret nel corpo della risposta.

    Esempio di configurazione del webhook

    Ad esempio, se il webhook riceve una richiesta POST con il seguente contenuto del corpo:

      {
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
  }

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

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

  // Example endpoint
  app.post("/rbm-webhook", (req, res) => {
    // Use the X-Goog-Webhook-Type header to route requests
    const webhookType = req.header('X-Goog-Webhook-Type');

    if (webhookType === 'verification') {
      const msg = req.body;
      if (msg.clientToken === myClientToken) {
          res.status(200).send(msg.secret);
          return;
      }
    }
    res.send(400);
    // Handle other webhook types
  });

  6. Nella console per sviluppatori, fai clic su Verifica. Dopo aver fatto clic su Verifica, Google invia una richiesta POST a tuo webhook con clientToken e secret come parametri nel corpo della richiesta. Quando RCS for Business verifica il webhook, la finestra di dialogo si chiude.

Identificare i tipi di richiesta

Per identificare il tipo di richiesta per tutte le richieste in arrivo al webhook, utilizza l'intestazione X-Goog-Webhook-Type.

L'intestazione può avere i seguenti valori:

  • verification: utilizzato per la procedura di verifica iniziale dell'endpoint.
  • message_callback: utilizzato per gli eventi relativi ai messaggi, ad esempio notifiche di digitazione o consegna e messaggi in arrivo dagli utenti.
  • agent_callback: utilizzato per gli eventi amministrativi specifici dell'agente, ad esempio le modifiche dello stato di lancio dell'agente.

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 i contenuti.

Per verificare che Google abbia inviato un messaggio che hai ricevuto:

  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 RCS for Business nell'elemento message.body della richiesta.
  3. Utilizzando il token client del webhook (che hai specificato quando hai configurato il webhook) come chiave, crea un HMAC SHA512 dei byte del payload del messaggio decodificato in base64 e codifica in base64 il risultato.
  4. Confronta l'hash X-Goog-Signature con l'hash che hai creato.
    • Se gli hash corrispondono, hai confermato che Google ha inviato il messaggio.

    • Se gli hash non corrispondono, controlla la procedura di hashing su un messaggio di cui sai che funziona.

      Se la procedura di hashing funziona correttamente e ricevi un messaggio che ritieni 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
    const headerHash = req.header('X-Goog-Signature');
    const userEventString = Buffer.from(requestBody.message.data, 'base64');
    const hmac = crypto.createHmac('sha512', myClientToken);
    const genHash = hmac.update(userEventString).digest('base64');

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);

Gestione dei messaggi

La restituzione di un valore diverso da 200 OK da un webhook è 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 che gestisca 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. Ecco alcuni 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 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. Eventuali errori o ritardi durante l'elaborazione possono influire sul codice di ritorno del webhook:

Elaborazione sincrona dei webhook

Comportamento in caso di errore di consegna

Se il webhook restituisce un valore diverso da uno stato 200 OK, la piattaforma RCS for Business utilizza un meccanismo di backoff e nuovi tentativi per riconsegnare i dati. Ciò significa che il sistema aumenta progressivamente il ritardo tra ogni tentativo di consegna, fino a raggiungere una frequenza massima di un nuovo tentativo ogni 10 minuti per ogni messaggio in attesa. Il ciclo di nuovi 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 singolo account partner condividono una singola coda. Per questo motivo, un errore in un webhook può bloccare l'intera coda, impedendo agli eventi utente di raggiungere il partner per tutti gli agenti.

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

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

Questo volume di nuovi 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.
  • Disaccoppia l'elaborazione: 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 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 di Google: utilizza il DNS inverso o l'intestazione X-Goog-Signatureanziché l'inserimento in lista consentita di IP fissi, poiché Google utilizza IP anycast dinamici. Per saperne di più 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

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

Avanti
Dialogflow