DataFirefly Webhooks — Guida completa

Introduzione

DataFirefly Webhooks collega il tuo negozio PrestaShop 8 e 9 a oltre 5000 applicazioni, in entrambe le direzioni. In uscita, il tuo negozio emette i suoi eventi (ordini, clienti, scorte…) verso Zapier, Make, n8n o qualsiasi endpoint HTTP. In entrata, gli stessi strumenti possono inviare dati al negozio tramite un’API sicura.

Il modulo si basa su tre pilastri: una coda asincrona (nessun ordine rallentato), ritentativi automatici con backoff esponenziale e una firma HMAC-SHA256 per garantire l’autenticità dei messaggi.

Installazione

1. Scarica l’archivio dfwebhooks.zip dal tuo account DataFirefly.
2. Nel back office, vai su Moduli > Gestore dei moduli > Carica un modulo e rilascia lo ZIP.
3. Fai clic su Installa e poi su Configura.
4. Arrivi alla schermata principale che mostra l’URL del worker cron e l’URL dell’API in entrata.

1. Pianificare il worker cron (flusso in uscita)

I webhook in uscita non vengono inviati immediatamente: vengono messi in coda e consegnati da un worker che attivi periodicamente. Copia l’URL del cron mostrato nella schermata di configurazione e pianificalo ogni 1-5 minuti.

*/2 * * * * curl -s "https://il-tuo-negozio.com/index.php?fc=module&module=dfwebhooks&controller=cron&token=IL_TUO_TOKEN" >/dev/null 2>&1

A ogni passaggio, il worker elabora fino a 50 consegne in attesa, applica i ritentativi necessari e ripulisce i vecchi registri secondo la conservazione configurata.

2. Creare un endpoint in uscita

Un endpoint collega un evento a un URL di destinazione. Dalla schermata principale, fai clic su Aggiungi e compila:

• Nome: un’etichetta interna (es. “Nuovo ordine → Zapier”).
• Evento: l’evento scatenante (vedi l’elenco più sotto).
• URL: incolla l’URL “Catch Hook” di Zapier o “Custom Webhook” di Make.
• Segreto di firma (opzionale): se impostato, ogni payload viene firmato con HMAC-SHA256.

Filtri condizionali

Puoi inviare un webhook solo quando determinate condizioni sono soddisfatte. Le regole sono in JSON e combinate con AND logico. Operatori disponibili: eq, neq, gt, gte, lt, lte, in, contains.

[{"field":"order.total_paid","op":"gte","value":100}]

Questo esempio attiva il webhook solo per gli ordini il cui totale pagato è maggiore o uguale a 100.

Mappatura dei campi

Per impostazione predefinita viene inviato il payload completo. Per inviare solo determinati campi in un formato preciso, definisci una mappatura: la chiave è il nome di output, il valore è il percorso all’interno del payload.

{"email":"customer.email","total":"order.total_paid"}

3. Eventi in uscita disponibili

• order.created — un ordine è appena stato convalidato.
• order.status.updated — lo stato di un ordine cambia.
• order.refunded — un ordine passa allo stato rimborsato.
• customer.created — un nuovo cliente si registra.
• address.created — viene creato un nuovo indirizzo.
• product.created — viene aggiunto un prodotto.
• product.updated — un prodotto viene modificato.
• product.stock.low — le scorte scendono sotto la soglia configurata.
• review.created — una recensione viene approvata (richiede un modulo recensioni compatibile).

4. API in entrata (Zapier/Make/n8n → PrestaShop)

L’API in entrata permette alle tue automazioni di modificare il negozio. È protetta da un token e, facoltativamente, da una firma HMAC.

Creare un token

Nel pannello Token in entrata, assegna un’etichetta, scegli gli scope consentiti (orders, products, customers) e, se vuoi, un segreto di firma. Il token generato va incollato nel tuo strumento.

Inviare una richiesta

Esegui un POST all’URL dell’API in entrata. Il token va nell’header X-DF-Token (o come parametro ?token=). Il corpo è un JSON con una action e un oggetto data.

POST https://il-tuo-negozio.com/index.php?fc=module&module=dfwebhooks&controller=api
X-DF-Token: IL_TUO_TOKEN
Content-Type: application/json

{"action":"order.status.update","data":{"id_order":42,"id_order_state":4}}

5. Azioni in entrata disponibili

• order.status.update (scope orders) — cambia lo stato di un ordine. Campi: id_order, id_order_state, send_email (opzionale).
• order.get (scope orders) — recupera un ordine. Campo: id_order.
• product.stock.update (scope products) — imposta le scorte. Campi: id_product, quantity, id_product_attribute (opzionale).
• product.upsert (scope products) — crea o aggiorna un prodotto tramite la sua reference.
• customer.upsert (scope customers) — crea o aggiorna un cliente tramite la sua email.
• customer.get (scope customers) — recupera un cliente tramite email o id_customer.

6. Verificare la firma HMAC

Se è configurato un segreto sull’endpoint (in uscita) o sul token (in entrata), il messaggio porta un header X-DF-Signature: sha256=.... Per verificarla in ricezione, ricalcola l’HMAC del corpo grezzo con il tuo segreto e confronta a tempo costante.

$expected = "sha256=" . hash_hmac("sha256", $rawBody, $secret);
if (hash_equals($expected, $signatureHeader)) {
    // firma valida
}

Calcola sempre l’HMAC sul corpo grezzo (non riserializzato), altrimenti la firma non corrisponderà.

7. Registro di consegna e reinvio

Il menu Webhooks Delivery Log elenca ogni tentativo con il suo stato:

• SENT — consegnato con un codice HTTP 2xx.
• PENDING — in coda, in attesa del prossimo passaggio del worker.
• FAILED — errore temporaneo, è pianificato un ritentativo.
• DEAD — errore definitivo dopo 6 tentativi.

I ritentativi seguono un backoff esponenziale: 1 minuto, 5 minuti, 30 minuti, 2 ore, poi 6 ore. Puoi forzare un nuovo invio in qualsiasi momento con il pulsante Replay e ispezionare il payload esatto dall’azione Visualizza.

8. Multinegozio, GDPR e modalità batch

Ogni endpoint e ogni token sono associati a un negozio specifico: i flussi di un negozio non finiscono mai in un altro. L’opzione Anonimizza i dati personali maschera e-mail, telefoni e nomi prima dell’invio, per restare conformi al GDPR quando la destinazione non deve ricevere dati identificativi. La modalità batch raggruppa gli invii per grandi volumi.

FAQ e risoluzione dei problemi

Non viene inviato alcun webhook. Verifica che il worker cron sia pianificato e che il suo URL (con il token corretto) risponda. Controlla il registro: se le righe restano in PENDING, il cron non è in esecuzione.

L’endpoint remoto restituisce un errore 401/403. Il tuo strumento potrebbe attendere una verifica della firma: imposta lo stesso segreto su entrambi i lati, oppure rimuovilo durante i test.

L’API in entrata restituisce “insufficient_scope”. Al token usato manca lo scope richiesto dall’azione. Modifica il token per spuntare lo scope corrispondente (orders, products o customers).

Il pulsante di test mostra un errore. Il pulsante Test invia un payload di esempio in modo sincrono: un errore indica di solito un URL irraggiungibile o un certificato TLS non valido sulla destinazione.