# Webhooks DataFirefly: volledige gids

> 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…

- Pagina: <https://www.datafirefly.com/nl/documentation/dfwebhooks/>
- Taal: nl
- Bijgewerkt op: 2026-09-16
- Andere talen: [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), [it](https://www.datafirefly.com/it/documentation/dfwebhooks/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfwebhooks/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfwebhooks/index.md)
- Index: <https://www.datafirefly.com/nl/documentation/llms.txt>

## 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

1. Download het archief `dfwebhooks.zip` vanuit uw DataFirefly-account.
2. Ga in de back-office naar _Modules > Module Manager > Een module uploaden_ en sleep de ZIP erin.
3. Klik op _Installeren_ en daarna op _Configureren_.
4. 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>&1
```

Bij 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 zijn `reference`.
- `customer.upsert` (scope customers) — maakt of werkt een klant bij op zijn `email`.
- `customer.get` (scope customers) — haalt een klant op via `email` of `id_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.