← Tutti gli articoli

Sviluppatori · 4 min · 19 agosto 2026

Sincronizzare gli iscritti alla newsletter di Webround e Brevo con Cloudflare Workers

Quando un cliente ha migrato il suo store su Webround, aveva già un account Brevo attivo con circa 3.000 contatti newsletter accumulati nel corso di più anni.

Tuttavia, la sua integrazione originale aveva smesso di funzionare e aveva iniziato ad accumulare una discrepanza significativa tra i contatti del suo e-commerce e quelli registrati su Brevo.

Il requisito era semplice: mantenere Webround e Brevo sincronizzati senza perdere la lista esistente, aggiungere tutti i contatti accumulati nel tempo che non erano stati sincronizzati, e fare in modo che una disiscrizione su un lato si rifletta anche sull'altro.

Questo significava tre cose: un'importazione massiva una tantum degli iscritti Webround esistenti in Brevo, un webhook da Webround a Brevo per nuove iscrizioni e disiscrizioni, e un webhook da Brevo a Webround per disiscrizioni e cancellazioni di contatti.

Tutto gira su un singolo Cloudflare Worker.

L'importazione massiva

Prima di configurare la sincronizzazione in tempo reale, bisognava allineare la lista esistente. Webround espone un endpoint paginato /store-customers con il filtro includeNewsletter=true, quindi lo script di importazione recupera tutti gli iscritti pagina per pagina e li invia a Brevo in batch da 150, restando entro i limiti dell'API di importazione di Brevo.

typescript
async function fetchAllNewsletterContacts() {
    const contacts = [];
    let page = 1;
    let totalPages = 1;

    while (page <= totalPages) {
        const res = await fetch(
            `${WR_API_URL}/store-customers?page=${page}&limit=100&includeNewsletter=true&includeDeleted=false`,
            { headers: wrHeaders }
        );
        const data = await res.json();
        totalPages = data.pagination.totalPages;

        for (const c of data.data) {
            if (c.email) contacts.push({ email: c.email, displayName: c.displayName });
        }
        page++;
    }

    return contacts;
}

async function importToBrevo(contacts) {
    const BATCH = 150;

    for (let i = 0; i < contacts.length; i += BATCH) {
        const batch = contacts.slice(i, i + BATCH);

        await fetch('https://api.brevo.com/v3/contacts/import', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json', 'api-key': BREVO_API_KEY },
            body: JSON.stringify({
                listIds: [BREVO_LIST_ID],
                updateExistingContacts: true,
                jsonBody: batch.map(c => ({
                    email: c.email,
                    attributes: { FIRSTNAME: c.displayName },
                })),
            }),
        });
    }
}

Il flag updateExistingContacts: true gestisce la deduplicazione in modo nativo: se un contatto esiste già su Brevo, Brevo lo aggiorna invece di creare un duplicato. Nessun bisogno di confrontare le liste a mano.

La sincronizzazione in tempo reale

Per evitare il problema originale di avere due liste di contatti non allineate, i webhook sono essenziali. Ci permettono di ascoltare gli eventi invece di fare polling periodico su entrambe le piattaforme.

Il Worker è in ascolto su due endpoint: /webhook/wr per gli eventi di Webround e /webhook/brevo per quelli di Brevo.

Webround -> Brevo

Webround emette gli eventi store.customer.newsletter.subscribed e store.customer.newsletter.unsubscribed. Il Worker valida la firma HMAC con un controllo sul timestamp per rifiutare le richieste scadute, poi chiama l'API di importazione di Brevo per aggiungere il contatto oppure l'endpoint di rimozione dalla lista per toglierlo. In questo modo, tutti gli utenti che si iscrivono o si disiscrivono attivamente dallo storefront restano sincronizzati con Brevo.

Webround firma ogni payload dei webhook con HMAC SHA-256 usando un secret condiviso, combinato con un timestamp per prevenire i replay attack:

typescript
export async function verifyWebroundWebhook(
    request: Request,
    secret: string
): Promise<{ valid: boolean; body: string }> {
    const signature = request.headers.get("X-Webhook-Signature");
    const timestamp = request.headers.get("X-Webhook-Timestamp");

    const ts = Number(timestamp);
    if (!Number.isFinite(ts) || Math.abs(Date.now() - ts) > 30_000) {
        return { valid: false, body: "" };
    }

    const body = await request.text();
    const key = await crypto.subtle.importKey(
        "raw",
        new TextEncoder().encode(secret),
        { name: "HMAC", hash: "SHA-256" },
        false,
        ["sign"]
    );
    const mac = await crypto.subtle.sign(
        "HMAC",
        key,
        new TextEncoder().encode(`${timestamp}.${body}`)
    );
    const expected = [...new Uint8Array(mac)]
        .map(b => b.toString(16).padStart(2, "0"))
        .join("");

    let diff = 0;
    for (let i = 0; i < expected.length; i++) {
        diff |= expected.charCodeAt(i) ^ signature!.charCodeAt(i);
    }

    return { valid: diff === 0, body };
}

Il confronto usa un ciclo a tempo costante per evitare i timing attack.

Brevo -> Webround

Brevo non firma i payload con HMAC. Invece, invia i webhook da un insieme fisso di range di IP e supporta un header con secret condiviso opzionale. Il Worker valida entrambi:

typescript
const BREVO_WEBHOOK_CIDRS = [
    { base: ip4ToInt("1.179.112.0"), mask: 0xFFFFF000 },
    { base: ip4ToInt("172.246.240.0"), mask: 0xFFFFF000 },
];

export function validateBrevoWebhook(request: Request, env: Env): boolean {
    const ip = request.headers.get("CF-Connecting-IP") ?? "";
    const secret = request.headers.get("x-brevo-secret") ?? "";
    return isBrevoIp(ip) && secret === env.BREVO_WEBHOOK_SECRET;
}

Quando Brevo emette un evento unsubscribe o contactDeleted, il Worker cerca il cliente su Webround tramite email e imposta il suo campo newsletter a false, così chiunque si disiscriva direttamente da un link in una email viene aggiornato anche su Webround:

typescript
export async function handleBrevoWebhook(
    body: { event?: string; email?: string },
    env: Env
): Promise<Response> {
    const { event, email } = body;
    if (!email) return new Response("Missing email", { status: 400 });

    switch (event) {
        case "unsubscribe":
        case "contactDeleted":
            return setNewsletterOnWebround(email, false, env);
        default:
            return new Response("ok", { status: 200 });
    }
}

Il routing completo del Worker

typescript
export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        const url = new URL(request.url);
        const path = url.pathname.includes("/apps/")
            ? "/" + url.pathname.split("/").slice(4).join("/")
            : url.pathname;

        if (path === "/webhook/wr" && request.method === "POST") {
            const { valid, body } = await verifyWebroundWebhook(request, env.WR_WEBHOOK_SECRET);
            if (!valid) return new Response("Unauthorized", { status: 401 });

            const envelope = JSON.parse(body) as {
                eventType: string;
                data: { email: string; displayName?: string };
            };

            if (envelope.eventType === "store.customer.newsletter.subscribed") {
                await addContacts(env, [{ email: envelope.data.email, displayName: envelope.data.displayName ?? envelope.data.email }]);
            }
            if (envelope.eventType === "store.customer.newsletter.unsubscribed") {
                await removeContacts(env, [envelope.data.email]);
            }

            return new Response("ok", { status: 200 });
        }

        if (path === "/webhook/brevo" && request.method === "POST") {
            if (!validateBrevoWebhook(request, env)) {
                return new Response("Unauthorized", { status: 401 });
            }
            const body = await request.json() as { event?: string; email?: string };
            return handleBrevoWebhook(body, env);
        }

        return new Response("Not found", { status: 404 });
    },
};

La normalizzazione del path in cima gestisce le App Extension di Webround, che prefissano l'URL con /apps/{id}/... quando il Worker è registrato come extension invece di essere chiamato direttamente. In un deployment standard di Cloudflare Workers il formato dell'URL è diverso, ma viene gestito dalla stessa normalizzazione.

Cosa copre

Un cliente si iscrive dallo storefront: il Worker lo aggiunge alla lista Brevo in tempo reale. Un cliente si disiscrive da una email di Brevo: il Worker imposta il suo flag newsletter a false su Webround. Un contatto viene cancellato su Brevo: stesso risultato. I due sistemi restano coerenti senza alcun intervento manuale né job batch periodici.

Il sorgente completo è su GitHub: https://github.com/WebroundAdmin/wr-brevo-integration

Costruito su Webround, una piattaforma e-commerce API-first: webround.com