# 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,…
- Pagina:
- Lingua: it
- Aggiornato il: 2026-06-25
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dfwebhooks/index.md), [en](https://www.datafirefly.com/en/documentation/dfwebhooks/index.md), [es](https://www.datafirefly.com/es/documentation/dfwebhooks/index.md), [de](https://www.datafirefly.com/de/documentation/dfwebhooks/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfwebhooks/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfwebhooks/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwebhooks/index.md)
- Indice:
## 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.
Non serve alcun piano a pagamento su Zapier, Make o n8n per iniziare: funziona qualsiasi servizio in grado di ricevere o inviare un webhook HTTP.
## 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.
Il token nell'URL protegge l'accesso al worker. Non condividerlo e non esporlo pubblicamente. Puoi usare un servizio esterno (cron-job.org, EasyCron) se il tuo hosting non offre attività cron.
## 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).
La soglia di scorte basse si imposta nel pannello _Impostazioni_ della schermata principale, insieme alla durata di conservazione dei registri.
## 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`.
Durante l'elaborazione delle richieste in entrata è attiva una **protezione anti-loop**: le modifiche che provocano non riattivano mai un webhook in uscita. Nessun rischio di loop infinito tra il tuo negozio e le tue automazioni.
## 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.