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 event webhooks in tempo reale di Bird sono uno strumento incredibilmente prezioso per i mittenti per avere dati automaticamente inviati ai loro sistemi. Questo può guidare l'automazione a valle come l'aggiornamento delle liste di distribuzione, l'attivazione di percorsi email automatizzati 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 il Bird Events API, le limitazioni sul numero di record restituiti in una singola richiesta o i limiti di velocità impostati sull'endpoint dell'API possono rendere entrambi questi metodi restrittivi per mittenti grandi e sofisticati.
I webhooks in tempo reale permettono a un mittente di configurare un endpoint dove Bird trasmette i dati, e i dati possono essere assimilati senza dover programmare lavori cron che estraggono i dati. Ci sono anche compromessi logistici nel estrarre i dati rispetto ad averli inviati a te, come dover identificare quale periodo di tempo e parametri utilizzare per ogni richiesta API. Se i periodi di tempo non sono perfettamente allineati, allora rischi di perdere dati, e se i periodi di tempo si sovrappongono allora devi gestire record di dati duplicati. Con i webhooks in tempo reale, i dati dell'evento sono semplicemente inviati al tuo endpoint mentre diventano disponibili all'interno di Bird.
Mentre i benefici di ricevere dati degli eventi in tempo reale per guidare processi di automazione a valle possono essere immediatamente compresi da molti mittenti, il processo effettivo per implementare e assimilare webhooks può essere intimorente. Questo può essere particolarmente vero se non si ha familiarità con i componenti tecnici di creare un endpoint e gestire i dati in modo programmatico. Ci sono servizi disponibili che assimileranno i dati di Bird webhook e ETL nel tuo database automaticamente - un esempio sarebbe StitchData, di cui abbiamo scritto sul blog in passato. Tuttavia, se desideri più controllo sul processo, puoi facilmente costruire i componenti da solo. La seguente è una semplice guida per aiutare i mittenti a sentirsi a proprio agio quando creano un Bird events webhook e assimilano i dati utilizzando l'infrastruttura all'interno di AWS.
Configurazione dell'Endpoint di Destinazione Webhook
Quando viene creato un evento Bird, vogliamo che i dati dell'evento vengano trasmessi in tempo reale a un endpoint su AWS in modo da poterli consumare e utilizzare programmaticamente. 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. Di seguito è riportato un diagramma ad alto livello del flusso di dati descritto:
Per implementare questo flusso di lavoro, costruiamo in realtà all'indietro partendo dalla creazione di un bucket S3 dove memorizzeremo i dati degli eventi e poi lavoriamo a ritroso, aggiungendo ciascun componente che alimenta ciò 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 memorizzarli, dobbiamo prima creare il nostro bucket S3 dove i dati saranno memorizzati. Per fare questo, navigare nel servizio S3 all'interno di AWS e premere “Create Bucket.” Ti verrà chiesto di assegnare un nome al tuo bucket e impostare la regione – assicurati di utilizzare la stessa regione del tuo ALB e della funzione lambda. Quando il tuo bucket S3 viene creato, sarà vuoto – se desideri organizzare i dati all'interno di una cartella, puoi creare ora la directory prevista, oppure la directory verrà creata quando la tua funzione lambda memorizzerà il file. In questo esempio, abbiamo chiamato il nostro bucket S3 “bird-webhooks” e creato una cartella chiamata “B Event Data” per memorizzare i dati degli eventi – vedrai questi nomi riferiti nella nostra funzione lambda di seguito.
Crea una Funzione Lambda per Consumarli Dati
L'elaborazione e la memorizzazione effettiva dei dati saranno svolte da una funzione lambda che viene invocata dal nostro application load balancer (ALB).
Il primo passo è creare la tua funzione lambda navigando nel servizio Lambda all'interno di AWS e facendo clic 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, usiamo 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 intestazioni complete e corpo. Il payload viene passato alla nostra funzione lambda utilizzando l'oggetto “event” come un dizionario. Puoi riferirti alle intestazioni e al corpo del payload in modo indipendente accedendo agli oggetti “headers” e “body” all'interno del payload. In questo esempio, leggeremo semplicemente l'intestazione “x-messagesystems-batch-id”, dove il batch ID è un valore unico creato da Bird per il batch del webhook, e lo useremo come nome del file quando memorizziamo il corpo come un flat-file in S3; tuttavia, potresti voler aggiungere funzionalità aggiuntive come controlli di autenticazione o gestione degli errori, se necessario.
Quando si memorizza il payload in un flat-file 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, memorizzeremo l'intero batch come un singolo file, il che aiuta a garantire che i dati siano raccolti e memorizzati prima che la connessione HTTP tra Bird e il tuo endpoint scada. Mentre potresti regolare le impostazioni di timeout della connessione sul tuo load balancer, non ci sono garanzie che la connessione non scada dal lato della trasmissione (in questo caso Bird) o che la connessione non venga terminata prima che la tua funzione lambda finisca di eseguire. È una best practice mantenere la tua funzione consumer il più efficiente possibile e riservare le attività di elaborazione dei dati a processi downstream ove possibile, come convertire il payload in formato JSON batch in un file CSV, o caricare i dati degli eventi in un database.
È importante notare che potresti dover aggiornare i permessi per la tua funzione lambda. Il tuo ruolo di esecuzione avrà bisogno delle autorizzazioni PutObject e GetObject per S3. È una best practice applicare il principio del privilegio minimo, quindi consiglio di impostare queste autorizzazioni solo per il bucket S3 in cui verranno memorizzati i payload del webhook.
Un esempio della nostra funzione lambda consumer può essere trovato qui.
Una nota veloce sul batch ID: Bird accorperà eventi in un singolo payload, dove ciascun 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 utilizzando 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 ritenterà automaticamente il batch utilizzando lo stesso batch ID. Ciò può accadere quando la tua funzione lambda è vicina al tempo massimo di andata e ritorno di 10 secondi ed è un motivo per ottimizzare la funzione consumer per ridurre il tempo di esecuzione.
Per gestire tutte le attività di elaborazione dei dati, consiglio di creare una funzione lambda separata che venga eseguita ogni volta che un nuovo file viene creato nel bucket S3 – in questo modo, l'elaborazione dei dati viene eseguita in modo asincrono rispetto alla trasmissione dei dati, e non c'è rischio di perdere dati a causa di una connessione terminata. Discuto la 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. Lo facciamo creando un application load balancer all'interno di AWS navigando su EC2 > Load Balancers e facendo clic su “Create Load Balancer.” Ti verrà chiesto di scegliere quale tipo di load balancer desideri creare – per questo, vogliamo creare un application load balancer. Dobbiamo usare un application load balancer (ALB) per costruire il nostro consumer perché i webhook degli eventi verranno inviati come una richiesta HTTP, e gli ALB sono utilizzati per il routing delle richieste HTTP all'interno di AWS. Potremmo implementare un HTTP Gateway come alternativa; tuttavia, usiamo 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 l'oggetto request di conseguenza.
Una volta creato il tuo ALB, ti verrà chiesto di assegnargli un nome e configurare lo schema e le impostazioni di accesso/sicurezza – poiché prevediamo di ricevere dati di eventi da una fonte esterna (Bird), vogliamo che il nostro ALB sia pubblico. Nella sezione “Ascoltatori e instradamento”, l'ALB dovrebbe ascoltare HTTPS sulla porta 443 e vogliamo creare un gruppo di destinazione che punti alla nostra funzione lambda in modo che il nostro ALB possa inoltrare le richieste in entrata alla funzione lambda consumer che abbiamo creato sopra. È necessario anche assicurarsi che il gruppo di sicurezza abbia il permesso di accettare il traffico attraverso la porta 443.
Crea un Record DNS per il Load Balancer
Per facilitarci l'uso del nostro ALB come endpoint, creeremo un record A nel DNS che punti al nostro ALB. Per questo, possiamo usare il servizio AWS Route 53 (o il tuo attuale provider DNS) e creare un record A per il nome host che desideri utilizzare per il tuo endpoint (ad es. spevents.<your_domain>). Il record A dovrebbe essere configurato per puntare all'ALB che abbiamo creato. Se stai usando Route 53 per gestire i record DNS, puoi riferirti direttamente all'istanza ALB abilitando l'opzione “Alias” e selezionando l'ALB; in caso contrario, se stai utilizzando un provider DNS esterno, dovresti puntare il record A all'indirizzo IP pubblico dell'istanza ALB.
Consiglio di usare uno strumento come Postman per testare che tutto sia stato configurato correttamente prima di abilitare il tuo webhook Bird. Puoi fare una richiesta POST al tuo endpoint e confermare che viene ricevuta una risposta. Se la tua richiesta POST non restituisce una risposta, potrebbe essere necessario ricontrollare che il tuo ALB stia ascoltando la porta corretta.
Crea un Webhook Bird
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 nella sezione Webhooks all'interno del tuo account Bird e fai clic su “Create Webhook.” Ti verrà chiesto di assegnare un nome al tuo webhook e fornire un URL di destinazione – la destinazione dovrebbe essere il nome host del record A che hai creato in precedenza. Nota che l'URL di destinazione potrebbe richiedere l'inclusione di “HTTPS://” nell'URL.
Una volta completato, verifica che il corretto sottoaccount e gli eventi siano selezionati, e premi “Create Webhook” per salvare la configurazione. I dati degli eventi per tutti i tipi di evento selezionati ora fluiranno al nostro URL di destinazione e verranno consumati dal nostro ALB per l'elaborazione a valle.
