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 distribuzione, l'attivazione di percorsi e-mail automatizzati o il popolamento di dashboard interni. Mentre gli stessi dati degli eventi possono essere accessibili tramite l'interfaccia utente Bird utilizzando la ricerca eventi o in modo programmatico sfruttando la Events API di Bird, le limitazioni sul numero di record restituiti in una singola richiesta o i limiti di frequenza imposti sull'endpoint API possono rendere entrambi questi metodi restrittivi per i mittenti grandi e sofisticati.
I webhook degli eventi in tempo reale permettono a un mittente di configurare un endpoint al quale Bird trasmette i dati, e i dati possono essere consumati senza dover programmare cron job che estraggano i dati. Ci sono anche compromessi logistici quando si estraggono i dati invece di averli inviati, come dover identificare quale periodo di tempo e parametri utilizzare per ciascuna richiesta API. Se i periodi di tempo non sono perfettamente allineati, si rischia di perdere dati, e se i periodi 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 degli eventi in tempo reale per guidare i processi di automazione a valle possono essere immediatamente compresi da molti mittenti, il processo effettivo per implementare e consumare i webhook può essere intimidatorio. Questo può essere particolarmente vero se non si ha familiarità con i componenti tecnici della creazione di un endpoint e della gestione dei dati in modo programmatico. Ci sono servizi disponibili che consumeranno i dati webhook di Bird e li ETL nel tuo database automaticamente – un esempio sarebbe StitchData, di cui abbiamo parlato in un blog in passato. Tuttavia, se desideri più controllo sul processo, puoi facilmente costruire i componenti da solo. Di seguito è riportata una guida semplice per aiutare i mittenti a sentirsi a loro agio quando creano un webhook degli eventi Bird e consumano i dati utilizzando l'infrastruttura all'interno di AWS.
Configurazione dell'Endpoint di Destinazione Webhook
Quando viene creato un evento Bird, desideriamo che i dati dell'evento vengano trasmessi in tempo reale a un endpoint su AWS in modo da poter consumare e utilizzare tali dati in maniera programmativa. I dati verranno 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 al contrario cominciando con la creazione di un bucket S3 dove memorizzeremo i nostri dati eventi e poi lavoriamo all'indietro – aggiungendo ogni 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 memorizzare i dati, dobbiamo prima creare il nostro bucket S3 dove i dati saranno memorizzati. Mentre S3 fornisce un eccellente spazio di archiviazione per i dati del webhook, le organizzazioni che utilizzano anche database PostgreSQL per l'elaborazione degli eventi dovrebbero implementare corrette procedure di backup e ripristino per proteggere i loro dati strutturati insieme alla loro strategia di archiviazione su S3. Per farlo, naviga nel servizio S3 all'interno di AWS e premi “Create Bucket.” Sarai invitato ad assegnare un nome al tuo bucket e 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 il direttorio previsto ora oppure sarà creato 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 nostri dati evento – vedrai questi nomi riferiti nella nostra funzione lambda di seguito.
Crea una Funzione Lambda per Consumare i Dati
L'elaborazione e l'archiviazione effettiva dei dati sarà eseguita da una funzione lambda convocata dal nostro application load balancer (ALB).
Il primo passo è creare la tua funzione lambda navigando nel servizio Lambda all'interno di AWS e cliccando “Create Function.” Sarai invitato ad assegnare un nome alla tua funzione lambda e selezionare quale linguaggio di programmazione usare per scrivere la tua funzione. In questo esempio, usiamo Python come linguaggio di runtime.
Ora dobbiamo sviluppare la nostra funzione lambda. Per un momento, assumiamo 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 con tutti gli header e il corpo. Il payload viene passato alla nostra funzione lambda usando l'oggetto “event” come un dizionario. Puoi fare riferimento agli header e al corpo del payload in modo indipendente accedendo agli oggetti “headers” e “body” all'interno del payload. In questo esempio semplicemente leggere l'header “x-messagesystems-batch-id,” dove l'ID batch è un valore unico creato da Bird per il batch del webhook, e usarlo come nome del file quando si memorizza il corpo come file piatto in S3; Tuttavia, potresti voler aggiungere funzionalità aggiuntive come controlli di autenticazione o gestione degli errori, se necessario.
Quando si memorizza il payload su un file piatto su S3, sarà necessario 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 unico 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. 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 l'esecuzione. È una buona pratica mantenere la tua funzione consumer il più efficiente possibile e riservare le attività di elaborazione dati per processi a valle quando 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 dei permessi PutObject e GetObject per S3. È una buona pratica far rispettare il principio del privilegio minimo, 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 raggrupperà eventi 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 l'API Event Webhooks o all'interno del tuo account Bird cliccando su un stream webhook e selezionando “Batch Status.” Nel caso in cui un payload del webhook non possa essere consegnato, come durante un timeout di connessione, Bird ritenterà automaticamente il batch usando lo stesso ID batch. Ciò può accadere quando la tua funzione lambda esegue vicino al tempo massimo di round-trip 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 esegue ogni volta che un nuovo file viene creato sul bucket S3 – in questo modo, l'elaborazione dei dati viene eseguita in modo asincrono alla trasmissione dei dati e non vi è alcun 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. Facciamo questo creando un application load balancer all'interno di AWS navigando su EC2 > Load Balancers e cliccando “Create Load Balancer.” Sarai invitato a scegliere quale tipo di load balancer desideri creare – per questo, desideriamo creare un application load balancer. Dobbiamo usare un application load balancer (ALB) per costruire il nostro consumer perché gli eventi webhook 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 ed economico rispetto all'HTTP Gateway. È importante notare che se scegli di usare un HTTP Gateway, il formato degli eventi potrebbe essere diverso rispetto a un ALB e quindi la tua funzione lambda dovrà gestire l'oggetto di richiesta di conseguenza.
Una volta che il tuo ALB è stato creato, sarai invitato ad assegnare un nome al tuo ALB e configurare lo schema e le impostazioni di accesso/sicurezza – poiché prevediamo di ricevere dati evento da una fonte esterna (Bird), vorremo che il nostro ALB sia orientato verso Internet. Sotto “Listener e routing,” l'ALB dovrebbe ascoltare l'HTTPS sulla porta 443, e vogliamo creare un gruppo di destinazione 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 attraverso la porta 443.
Crea un Record DNS per il Load Balancer
Per rendere più facile per noi usare il nostro ALB come endpoint, creeremo un record A in 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 (es. spevents.<your_domain>). Quando lavori con DNS su larga scala su AWS, sii consapevole che ci sono limiti DNS non documentati che possono influenzare applicazioni ad alto volume, specialmente quelle che gestiscono grandi quantità di traffico in uscita come i sistemi di consegna email. Il record A dovrebbe essere configurato per puntare all'ALB che abbiamo creato. Se stai usando Route 53 per gestire i record DNS, puoi fare riferimento direttamente all'istanza ALB abilitando “Alias” e selezionando l'ALB; altrimenti, se stai usando 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 venga ricevuta una risposta. Se la tua richiesta POST non restituisce una risposta, potresti dover ricontrollare che il tuo ALB stia ascoltando sulla porta corretta.
Crea un Webhook Bird
Ora siamo pronti per creare il webhook in Bird e usare 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 clicca “Create Webhook.” Sarai invitato ad 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 che “HTTPS://” sia incluso nell'URL.
Una volta completato, verifica che il sottoaccount corretto e gli eventi siano selezionati, e premi “Create Webhook” per salvare la tua configurazione. I dati degli eventi per tutti i tipi di eventi selezionati ora fluiranno al nostro URL di destinazione e saranno consumati dal nostro ALB per l'elaborazione a valle.
