Webhooks DataFirefly: volledige gids
Installatie, configuratie en gebruik van de bidirectionele webhooks-connector: uitgaande flow, inkomende API, HMAC-handtekening, asynchrone wachtrij en leveringslogboek.
Overzicht
Webhooks DataFirefly verbindt uw PrestaShop 8- en 9-winkel met meer dan 5000 applicaties, in beide richtingen. Uitgaand stuurt uw winkel haar events (bestellingen, klanten, voorraad…) naar Zapier, Make, n8n of elk ander HTTP-endpoint. Inkomend kunnen diezelfde tools gegevens naar de winkel pushen via een beveiligde API.
De module steunt op drie pijlers: een asynchrone wachtrij (geen enkele vertraagde bestelling), automatische herpogingen met exponentiële backoff, en een HMAC-SHA256-handtekening om de authenticiteit van de berichten te garanderen.
U hebt geen enkel betaald abonnement bij Zapier, Make of n8n nodig om te starten: elke dienst die een HTTP-webhook kan ontvangen of versturen, werkt.
Installatie
- Download het archief
dfwebhooks.zipvanuit uw DataFirefly-account. - Ga in de back-office naar Modules > Module Manager > Een module uploaden en sleep de ZIP erin.
- Klik op Installeren en daarna op Configureren.
- U komt op het hoofdscherm dat de URL van de cronworker en de URL van de inkomende API toont.
1. De cronworker plannen (uitgaande flow)
De uitgaande webhooks worden niet onmiddellijk verstuurd: ze worden in de wachtrij gezet en daarna afgeleverd door een worker die u periodiek activeert. Kopieer de cron-URL van het configuratiescherm en plan haar elke 1 tot 5 minuten.
*/2 * * * * curl -s "https://uw-winkel.com/index.php?fc=module&module=dfwebhooks&controller=cron&token=UW_TOKEN" >/dev/null 2>&1Bij elke run verwerkt de worker tot 50 wachtende leveringen, past hij de nodige herpogingen toe en schoont hij de oude logboeken op volgens de geconfigureerde bewaartermijn.
Het token in de URL beschermt de toegang tot de worker. Deel het niet en stel het niet publiekelijk bloot. U kunt een externe dienst gebruiken (cron-job.org, EasyCron) als uw hosting geen crontaken aanbiedt.
2. Een uitgaand endpoint aanmaken
Een endpoint koppelt een event aan een bestemmings-URL. Klik vanaf het hoofdscherm op Toevoegen en vul in:
- Naam: een intern label (bijv. “Nieuwe bestelling → Zapier”).
- Event: het triggerende event (zie de lijst hieronder).
- URL: plak de “Catch Hook”-URL van Zapier of de “Custom Webhook” van Make.
- Handtekeninggeheim (optioneel): indien ingevuld wordt elke payload ondertekend met HMAC-SHA256.
Voorwaardelijke filters
U kunt een webhook alleen versturen wanneer aan bepaalde voorwaarden is voldaan. De regels zijn in JSON-formaat en worden gecombineerd met logische EN. Beschikbare operatoren: eq, neq, gt, gte, lt, lte, in, contains.
[{"field":"order.total_paid","op":"gte","value":100}]Dit voorbeeld activeert de webhook alleen voor bestellingen waarvan het betaalde totaal groter dan of gelijk aan 100 is.
Veldmapping
Standaard wordt de volledige payload verstuurd. Om alleen bepaalde velden in een precies formaat te versturen, definieert u een mapping: de sleutel is de uitvoernaam, de waarde het pad in de payload.
{"email":"customer.email","total":"order.total_paid"}3. Beschikbare uitgaande events
order.created— een bestelling is zojuist gevalideerd.order.status.updated— de status van een bestelling verandert.order.refunded— een bestelling gaat naar de status terugbetaald.customer.created— een nieuwe klant registreert zich.address.created— een nieuw adres wordt aangemaakt.product.created— een product wordt toegevoegd.product.updated— een product wordt gewijzigd.product.stock.low— de voorraad zakt onder de geconfigureerde drempel.review.created— een review wordt gevalideerd (vereist een compatibele reviewmodule).
De lage-voorraaddrempel stelt u in via het paneel Instellingen van het hoofdscherm, net als de bewaartermijn van de logboeken.
4. Inkomende API (Zapier/Make/n8n → PrestaShop)
De inkomende API laat uw automatiseringen de winkel wijzigen. Ze is beveiligd met een token en, optioneel, met een HMAC-handtekening.
Een token aanmaken
Geef in het paneel Inkomende tokens een label, kies de toegestane scopes (orders, products, customers) en, als u wilt, een handtekeninggeheim. Het gegenereerde token plakt u in uw tool.
Een verzoek versturen
Voer een POST uit op de URL van de inkomende API. Het token gaat in de header X-DF-Token (of als parameter ?token=). De body is JSON met een action en een object data.
POST https://uw-winkel.com/index.php?fc=module&module=dfwebhooks&controller=api
X-DF-Token: UW_TOKEN
Content-Type: application/json
{"action":"order.status.update","data":{"id_order":42,"id_order_state":4}}5. Beschikbare inkomende acties
order.status.update(scope orders) — wijzigt de status van een bestelling. Velden:id_order,id_order_state,send_email(optioneel).order.get(scope orders) — haalt een bestelling op. Veld:id_order.product.stock.update(scope products) — stelt de voorraad vast. Velden:id_product,quantity,id_product_attribute(optioneel).product.upsert(scope products) — maakt of werkt een product bij op zijnreference.customer.upsert(scope customers) — maakt of werkt een klant bij op zijnemail.customer.get(scope customers) — haalt een klant op viaemailofid_customer.
Tijdens het verwerken van inkomende verzoeken is een anti-lusbeveiliging actief: de wijzigingen die ze veroorzaken, triggeren nooit opnieuw een uitgaande webhook. Geen enkel risico op een oneindige lus tussen uw winkel en uw automatiseringen.
6. De HMAC-handtekening verifiëren
Is een geheim geconfigureerd op het endpoint (uitgaand) of het token (inkomend), dan draagt het bericht een header X-DF-Signature: sha256=.... Herbereken voor de verificatie aan ontvangstzijde de HMAC van de ruwe body met uw geheim en vergelijk in constante tijd.
$expected = "sha256=" . hash_hmac("sha256", $rawBody, $secret);
if (hash_equals($expected, $signatureHeader)) {
// handtekening geldig
}Vergelijk altijd de HMAC berekend op de ruwe body (niet opnieuw geserialiseerd), anders komt de handtekening niet overeen.
7. Leveringslogboek en replay
Het menu Webhooks Delivery Log toont elke poging met haar status:
- SENT — afgeleverd met een HTTP-code 2xx.
- PENDING — in de wachtrij, wachtend op de volgende workerrun.
- FAILED — tijdelijke fout, een herpoging is gepland.
- DEAD — definitieve fout na 6 pogingen.
De herpogingen volgen een exponentiële backoff: 1 minuut, 5 minuten, 30 minuten, 2 uur, daarna 6 uur. U kunt op elk moment een nieuwe verzending forceren via de knop Replay, en de exacte payload inspecteren via de actie Bekijken.
8. Multistore, AVG en batchmodus
Elk endpoint en elk token is gekoppeld aan een specifieke winkel: de flows van de ene winkel lekken nooit naar een andere. De optie Persoonsgegevens anonimiseren maskeert e-mailadressen, telefoonnummers en namen vóór de verzending, om AVG-conform te blijven wanneer de bestemming geen persoonsgegevens mag ontvangen. De batchmodus groepeert de verzendingen voor grote volumes.
FAQ en probleemoplossing
Er wordt geen enkele webhook verstuurd. Controleer of de cronworker daadwerkelijk is gepland en of zijn URL (met het juiste token) antwoordt. Raadpleeg het logboek: blijven de regels op PENDING, dan draait de cron niet.
Het externe endpoint geeft een 401/403-fout terug. Uw tool verwacht misschien een handtekeningverificatie: vul aan beide kanten hetzelfde geheim in, of verwijder het tijdens de tests.
De inkomende API geeft “insufficient_scope” terug. Het gebruikte token heeft niet de scope die de actie vereist. Wijzig het token om de bijbehorende scope aan te vinken (orders, products of customers).
De testpagina toont een fout. De knop Test verstuurt synchroon een voorbeeldpayload: een fout wijst doorgaans op een onbereikbare URL of een ongeldig TLS-certificaat aan bestemmingszijde.