Configure your webhook

A webhook is an HTTP POST request that Cartflox sends to your server on every payment status change. It is the reliable way to validate an order.

From the dashboard

In API and Logs, enter the receiving URL. It must be public and use HTTPS: local addresses and private networks are rejected.

Through the API

GET/v1/config/webhookRead the configured URL

PATCH/v1/config/webhookSet or change the address, choose the events

Field	Type	Description
webhookUrl	string	Public https address. An empty string removes the webhook.
mode	string	live (default with a production key) or test: which address is being set. See Test mode.
events	string[]	The events to receive, among those listed in Events. Absent or complete: all of them.

curl

curl -X PATCH https://cartflox.com/api/v1/config/webhook \
  -H "Authorization: Bearer af_live_sec_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": "https://mystore.com/webhooks/cartflox", "events": ["payment.completed", "payment.failed", "payment.cancelled"] }'

200 OK

{
  "success": true,
  "webhookUrl": "https://mystore.com/webhooks/cartflox",
  "testWebhookUrl": null,
  "events": ["payment.completed", "payment.failed", "payment.cancelled"],
  "available_events": ["payment.completed", "payment.failed", "payment.cancelled", "payment.updated", "transfer.succeeded", "transfer.failed"]
}

Delivery and retries

• Timeout: 10 seconds. Respond 2xx immediately and process afterwards.
• On failure (network error, non-2xx response, timeout): up to 10 attempts over roughly 72 hours (1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h, 24 h, 24 h), then a notification in your dashboard.
• Every request is logged and can be resent manually: Log and retries.
• The same event can therefore arrive twice, for example if your server responded too late: make your processing idempotent, relying on the X-Afriflow-Delivery header, or on data.id and data.status.
• A missed webhook can also be caught up by checking the session status.