DataFirefly Webhooks — Complete Guide

Overview

DataFirefly Webhooks connects your PrestaShop 8 and 9 store to 5000+ apps, in both directions. Outbound, your store emits events (orders, customers, stock…) to Zapier, Make, n8n or any HTTP endpoint. Inbound, those same tools can push data into the store through a secured API.

The module rests on three pillars: an async queue (no order ever slowed down), automatic retries with exponential backoff, and HMAC-SHA256 signing to guarantee message authenticity.

Installation

1. Download the dfwebhooks.zip archive from your DataFirefly account.
2. In the back office, go to Modules > Module Manager > Upload a module and drop the ZIP.
3. Click Install, then Configure.
4. You land on the main screen showing the cron worker URL and the inbound API URL.

1. Schedule the cron worker (outbound flow)

Outbound webhooks are not sent immediately: they are queued and delivered by a worker you trigger periodically. Copy the cron URL shown on the configuration screen and schedule it every 1 to 5 minutes.

*/2 * * * * curl -s "https://your-store.com/index.php?fc=module&module=dfwebhooks&controller=cron&token=YOUR_TOKEN" >/dev/null 2>&1

On each run, the worker processes up to 50 pending deliveries, applies the necessary retries and purges old logs according to the configured retention.

2. Create an outbound endpoint

An endpoint links an event to a destination URL. From the main screen, click Add, then fill in:

• Name: an internal label (e.g. “New order → Zapier”).
• Event: the trigger event (see the list below).
• URL: paste the “Catch Hook” URL from Zapier or “Custom Webhook” from Make.
• Signing secret (optional): if set, every payload is signed with HMAC-SHA256.

Conditional filters

You can send a webhook only when certain conditions are met. Rules are in JSON and combined with logical AND. Available operators: eq, neq, gt, gte, lt, lte, in, contains.

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

This example fires the webhook only for orders whose total paid is greater than or equal to 100.

Field mapping

By default the full payload is sent. To send only certain fields in a precise shape, define a mapping: the key is the output name, the value is the path inside the payload.

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

3. Available outbound events

• order.created — an order has just been validated.
• order.status.updated — an order’s status changes.
• order.refunded — an order moves to the refunded status.
• customer.created — a new customer signs up.
• address.created — a new address is created.
• product.created — a product is added.
• product.updated — a product is modified.
• product.stock.low — stock drops below the configured threshold.
• review.created — a review is approved (requires a compatible reviews module).

4. Inbound API (Zapier/Make/n8n → PrestaShop)

The inbound API lets your automations modify the store. It is protected by a token and, optionally, an HMAC signature.

Create a token

In the Inbound tokens panel, give it a label, choose the allowed scopes (orders, products, customers) and, if you wish, a signing secret. The generated token goes into your tool.

Send a request

Make a POST to the inbound API URL. The token goes in the X-DF-Token header (or as a ?token= parameter). The body is JSON with an action and a data object.

POST https://your-store.com/index.php?fc=module&module=dfwebhooks&controller=api
X-DF-Token: YOUR_TOKEN
Content-Type: application/json

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

5. Available inbound actions

• order.status.update (scope orders) — changes an order’s status. Fields: id_order, id_order_state, send_email (optional).
• order.get (scope orders) — fetches an order. Field: id_order.
• product.stock.update (scope products) — sets stock. Fields: id_product, quantity, id_product_attribute (optional).
• product.upsert (scope products) — creates or updates a product by its reference.
• customer.upsert (scope customers) — creates or updates a customer by their email.
• customer.get (scope customers) — fetches a customer by email or id_customer.

6. Verify the HMAC signature

If a secret is configured on the endpoint (outbound) or the token (inbound), the message carries an X-DF-Signature: sha256=... header. To verify it on reception, recompute the HMAC of the raw body with your secret and compare in constant time.

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

Always compute the HMAC over the raw body (not a re-serialized one), otherwise the signature will not match.

7. Delivery log and replay

The Webhooks Delivery Log menu lists every attempt with its status:

• SENT — delivered with an HTTP 2xx code.
• PENDING — queued, waiting for the next worker run.
• FAILED — temporary failure, a retry is scheduled.
• DEAD — permanent failure after 6 attempts.

Retries follow an exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, then 6 hours. You can force a new send at any time via the Replay button, and inspect the exact payload from the View action.

8. Multistore, GDPR and batch mode

Every endpoint and every token is scoped to a specific shop: one shop’s flows never leak into another. The Anonymize personal data option masks emails, phones and names before sending, to stay GDPR-compliant when the destination must not receive identifying data. Batch mode groups sends for high volumes.

FAQ and troubleshooting

No webhook is sent. Check that the cron worker is scheduled and that its URL (with the right token) responds. Check the log: if rows stay PENDING, the cron is not running.

The remote endpoint returns a 401/403 error. Your tool may expect a signature check: set the same secret on both sides, or remove it during testing.

The inbound API returns “insufficient_scope”. The token used lacks the scope required by the action. Edit the token to tick the matching scope (orders, products or customers).

The test button shows a failure. The Test button sends a sample payload synchronously: a failure usually means an unreachable URL or an invalid TLS certificate on the destination.