Di seguito è riportata una semplice guida per aiutare i mittenti a sentirsi a proprio agio quando creano un webhook per eventi Bird e consumano i dati utilizzando l'infrastruttura di AWS.
I webhook degli eventi in tempo reale di Bird sono uno strumento incredibilmente prezioso per i mittenti per avere i dati automaticamente inviati ai loro sistemi. Questo può guidare l'automazione a valle, come l'aggiornamento delle liste di mailing, l'attivazione di percorsi di email automatici o il popolamento di dashboard interni. Mentre gli stessi dati degli eventi possono essere accessibili tramite l'interfaccia Bird utilizzando Event Search, o programmaticamente sfruttando l'Events API di Bird, le limitazioni imposte sul numero di record restituiti in una singola richiesta o i limiti di velocità imposti sull'endpoint API possono rendere entrambi questi metodi restrittivi per mittenti di grandi dimensioni e sofisticati.
I webhook degli eventi in tempo reale consentono a un mittente di configurare un endpoint al quale Bird trasmette i dati, e i dati possono essere consumati senza dover pianificare i cron job che estraggono i dati. Ci sono anche compromessi logistici quando si estraggono i dati rispetto ad avere i dati inviati a te, come dover identificare quale periodo di tempo e parametri utilizzare per ogni richiesta API. Se i periodi di tempo non sono allineati perfettamente, si rischia di perdere dati e, se i periodi di tempo si sovrappongono, è necessario gestire i record di dati duplicati. Con i webhook in tempo reale, i dati degli eventi vengono semplicemente inviati al tuo endpoint non appena diventano disponibili all'interno di Bird.
Mentre i benefici di ricevere dati di eventi in tempo reale per guidare i processi di automazione a valle possono essere compresi immediatamente da molti mittenti, il processo effettivo per implementare e consumare i webhook può risultare intimidatorio. Questo può essere particolarmente vero se non si è familiari con i componenti tecnici della creazione di un endpoint e della gestione dei dati a livello programmatico. Sono disponibili servizi che consumano i dati webhook di Bird e li inseriscono automaticamente nel database tramite ETL - un esempio sarebbe StitchData, di cui abbiamo parlato in passato sul blog. Tuttavia, se desideri avere più controllo sul processo, puoi facilmente creare i componenti da solo. Di seguito è riportata una semplice guida per aiutare i mittenti a sentirsi a proprio agio quando creano un webhook degli eventi di Bird e consumano i dati usando l'infrastruttura all'interno di AWS.
Configurazione dell'Endpoint di Destinazione Webhook
Quando viene creato un evento Bird, vogliamo che i dati dell'evento siano trasmessi in tempo reale a un endpoint in AWS in modo da poterli consumare e utilizzare programmando. I dati saranno inviati da Bird a un endpoint di destinazione, che inoltrerà il payload a una funzione lambda che elaborerà e memorizzerà i dati in un bucket S3. Un diagramma ad alto livello del flusso di dati descritto può essere visto di seguito:
Per implementare questo flusso di lavoro, costruiamo effettivamente in ordine inverso iniziando con la creazione di un bucket S3 dove memorizzeremo i nostri dati evento e poi lavoriamo all'indietro, aggiungendo ogni componente che alimenta in quello che abbiamo costruito.
Crea un Bucket S3 per Memorizzare i Dati del Webhook
Prima di creare il nostro load balancer per accettare i dati, o la nostra funzione lambda per memorizzare i dati, dobbiamo prima creare il nostro bucket S3 dove i dati saranno memorizzati. Per fare ciò, naviga al servizio S3 all'interno di AWS e premi “Create Bucket.” Ti verrà chiesto di assegnare un nome al tuo bucket e di impostare la regione – assicurati di usare la stessa regione del tuo ALB e della funzione lambda. Quando il tuo bucket S3 è creato, sarà vuoto - se desideri organizzare i dati all'interno di una cartella, puoi creare ora la directory desiderata, oppure la directory sarà creata quando la tua funzione lambda memorizza il file. In questo esempio, abbiamo chiamato il nostro bucket S3 “bird-webhooks” e abbiamo creato una cartella chiamata “B Event Data” per memorizzare i nostri dati evento - vedrai questi nomi menzionati nella nostra funzione lambda di seguito.
Crea una Funzione Lambda per Consumare i Dati
L'elaborazione e la memorizzazione effettiva dei dati sarà eseguita da una funzione lambda che viene invocata dal nostro Application Load Balancer (ALB).
Il primo passo è creare la tua funzione lambda navigando al servizio Lambda all'interno di AWS e cliccando su “Create Function.” Ti verrà chiesto di assegnare un nome alla tua funzione lambda e di selezionare il linguaggio di programmazione in cui scrivere la tua funzione. Per questo esempio, utilizziamo Python come linguaggio di runtime.
Ora dobbiamo sviluppare la nostra funzione lambda. Per un momento, supponiamo che il nostro Application Load Balancer sia stato configurato e stia inoltrando il payload del webhook alla nostra funzione lambda – la lambda riceverà un payload che include tutte le intestazioni e il corpo. Il payload viene passato alla nostra funzione lambda usando l'oggetto “event” come dizionario. Puoi riferirti alle intestazioni e al corpo del payload indipendentemente accedendo agli oggetti “headers” e “body” all'interno del payload. In questo esempio, leggeremo semplicemente l'intestazione “x-messagesystems-batch-id,” dove l'ID batch è un valore unico creato da Bird per il batch del webhook, e lo usiamo come nome file quando memorizziamo il corpo come file piatto in S3; tuttavia, potresti voler aggiungere funzionalità aggiuntive come controlli di autenticazione o gestione degli errori, se necessario.
Quando memorizziamo il payload in un file piatto su S3, dovremo definire il nome del bucket S3, la posizione e il nome del file dove i dati del payload saranno memorizzati. Nella nostra funzione lambda di esempio, lo facciamo all'interno della funzione “store_batch.” In questo esempio, andremo a memorizzare l'intero batch come un unico file, il che aiuta ad assicurare che i dati siano raccolti e memorizzati prima che la connessione HTTP tra Bird e il tuo endpoint scada. Anche se potresti regolare le impostazioni di timeout della connessione sul tuo load balancer, non ci sono garanzie che la connessione non scada sul lato della trasmissione (in questo caso Bird) o che la connessione non venga terminata prima che la tua funzione lambda finisca di eseguire. È una buona pratica mantenere la tua funzione di consumatore il più efficiente possibile e riservare le attività di elaborazione dei dati per processi downstream dove possibile - come convertire il payload formattato in JSON in un file CSV, o caricare i dati evento in un database.
È importante notare che potresti dover aggiornare i permessi per la tua funzione lambda. Il tuo ruolo di esecuzione avrà bisogno dei permessi PutObject e GetObject per S3. È una buona pratica far rispettare il principio del minimo privilegio, quindi consiglio di impostare questi permessi solo per il bucket S3 dove i payload del webhook saranno memorizzati.
Un esempio della nostra funzione lambda consumer può essere trovato qui.
Una breve nota sull'ID batch: Bird batch events in un unico payload, dove ogni batch può contenere da 1 a 350 o più record di eventi. Al batch verrà assegnato un ID batch unico, che può essere utilizzato per visualizzare lo stato del batch sfruttando il Event Webhooks API o all'interno del tuo account Bird cliccando su un webhook stream e selezionando “Batch Status.” Nel caso in cui un payload del webhook non potesse essere consegnato, come durante un timeout della connessione, Bird automaticamente ritenta il batch utilizzando lo stesso ID batch. Questo può accadere quando la tua funzione lambda sta funzionando vicino al tempo di andata e ritorno massimo di 10 secondi ed è una ragione per ottimizzare la funzione di consumatore per ridurre il tempo di esecuzione.
Per gestire tutte le attività di elaborazione dei dati, consiglio di creare una funzione lambda separata che si esegua ogni volta che un nuovo file viene creato sul bucket S3 – in questo modo, l'elaborazione dei dati viene eseguita asincronamente rispetto alla trasmissione dei dati, e non c'è rischio di perdita di dati a causa di una connessione terminata. Discuto della funzione lambda di elaborazione in una sezione successiva.
Crea un Application Load Balancer
Per ricevere un payload del webhook, dobbiamo fornire un endpoint a cui inviare i payload. Facciamo questo creando un application load balancer all'interno di AWS navigando a EC2 > Load Balancers e cliccando su “Create Load Balancer.” Ti verrà chiesto di scegliere quale tipo di load balancer vuoi creare – per questo, vogliamo creare un application load balancer. Abbiamo bisogno di un application load balancer (ALB) per costruire il nostro consumatore perché gli event webhooks saranno inviati come una richiesta HTTP, e gli ALB sono utilizzati per instradare richieste HTTP all'interno di AWS. Potremmo implementare un HTTP Gateway come alternativa; tuttavia, utilizziamo un ALB per questo progetto perché è più leggero e conveniente rispetto all'HTTP Gateway. È importante notare che se scegli di utilizzare un HTTP Gateway, il formato dell'evento potrebbe essere diverso rispetto a un ALB, e quindi la tua funzione lambda dovrà gestire di conseguenza l'oggetto della richiesta.
Una volta che il tuo ALB è stato creato, ti verrà chiesto di assegnare un nome al tuo ALB e configurare le impostazioni di schema e accesso/sicurezza – poiché pianifichiamo di ricevere dati evento da una fonte esterna (Bird), vorremo che il nostro ALB sia accessibile dal web. Sotto “Ascoltatori e instradamento,” l'ALB dovrebbe ascoltare sui porti HTTPS su 443, e vogliamo creare un gruppo Target che punti alla nostra funzione lambda in modo che il nostro ALB inoltrerà le richieste in entrata alla funzione lambda consumer che abbiamo creato sopra. Devi anche assicurarti che il gruppo di sicurezza abbia il permesso di accettare traffico tramite la porta 443.
Crea un Record DNS per il Load Balancer
Per rendere più facile per noi utilizzare il nostro ALB come endpoint, creeremo un record A nel DNS che punti al nostro ALB. Per fare questo, possiamo utilizzare il servizio AWS Route 53 (o il tuo attuale provider DNS) e creare un record A per il nome host che vuoi usare per il tuo endpoint (es. spevents.<tuo_dominio>). Il record A dovrebbe essere configurato per puntare all'ALB che abbiamo creato. Se stai utilizzando Route 53 per gestire i record DNS, puoi fare riferimento direttamente all'istanza ALB abilitando “Alias” e selezionando l'ALB; altrimenti, se stai utilizzando un provider DNS esterno, dovresti puntare il record A all'indirizzo IP pubblico dell'istanza ALB.
Consiglio di utilizzare uno strumento come Postman per testare che tutto sia stato configurato correttamente prima di abilitare il tuo webhook Bird. Puoi effettuare una richiesta POST al tuo endpoint e confermare che viene ricevuta una risposta. Se la tua richiesta POST non ritorna una risposta, potresti dover ricontrollare che il tuo ALB stia ascoltando sulla porta corretta.
Crea un Bird Webhook
Ora siamo pronti a creare il webhook in Bird e utilizzare il nome host definito dal record A sopra come nostro endpoint di destinazione. Per creare il webhook, naviga alla sezione Webhooks all'interno del tuo account Bird e clicca su “Create Webhook.” Ti verrà chiesto di assegnare un nome al tuo webhook e fornire un URL di destinazione – il target dovrebbe essere il nome host del record A che hai creato in precedenza. Nota che l'URL di destinazione potrebbe richiedere che “HTTPS://” sia incluso nell'URL.
Una volta completato, verifica che il sottoconto corretto e gli eventi siano selezionati, e premi “Create Webhook” per salvare la tua configurazione. I dati evento per tutti i tipi di eventi selezionati ora verranno trasmessi al nostro URL di destinazione e consumati dal nostro ALB per l'elaborazione downstream.
