DEVELOPER TOOLS

Webhooks

Receive reliable order and payment updates directly on your server.

Receive events as they happen

Webhooks are HTTPS requests sent to your server when an order or payment changes state. They let your backend react even when the customer closes Checkout, loses connectivity, or never returns to your website.

Use webhooks as a server-side signal, then verify.

Authenticate every delivery and confirm the authoritative payment state before fulfilment.

How webhooks work

Create or update a webhook endpoint and select the required event strings.

Receive

Accept the POST request over HTTPS and retain the unmodified request body for verification.

Authenticate

Verify the delivery using the signing details configured for your FiatPe webhook.

Process once

Deduplicate the event, persist it, and apply only a valid forward state transition.

Acknowledge

Return a 2xx response quickly and move slow business work to a queue.

List of Webhook Events

Order

Track when the complete order has reached a paid state.

order.paid

Payments

Track payment authorisation, capture, and failure state changes.

payment.*

Order of webhook delivery

Webhook events are normally delivered in the order in which they occur, but delivery order is not guaranteed. A network interruption, timeout, or unavailable merchant server can cause one delivery to fail while a later event is delivered successfully. When FiatPe retries the failed event, it may therefore arrive after newer events. The same webhook may also be delivered more than once.

Do not use arrival order as the source of truth.

Identify events by their payment or order ID, make processing idempotent, and apply only valid state transitions. If an event appears older than the state already stored, retrieve the latest payment or order status before taking action.

Expect duplicate, delayed, retried, and out-of-order events.
Use the X-FiatPe-Idempotency request header as the delivery's idempotency key. Store it with a unique constraint and skip business processing when the same key has already completed.
Return a 2xx response quickly after safely accepting an event.
Never move a completed payment back to a pending, failed, or cancelled state.

Best practices

Use separate webhook configuration and signing secrets for Test and Live modes.
Allow duplicate, delayed, and out-of-order deliveries.
Store the X-FiatPe-Idempotency header value as a unique processed-delivery key and make handlers idempotent.
Never log secrets, full Authorization values, or unnecessary customer payment data.
Do not move a successful transaction back to failed or cancelled.