Webhook Event Catalog

Simpler delivers webhook events to notify your system of state changes that happen outside the synchronous request/response flow — payment confirmations for asynchronous methods, cancellations, and expiries.

This page lists every event type currently emitted. The payload shape for each event is defined in the OpenAPI spec.

Events

Event type	When it fires	Values
ORDER_UPDATED	The payment state of an order paid with an asynchronous method changed; specific transitions are encoded in the status field of the payload.	PAYMENT_SUCCESS, PAYMENT_FAILED
REFUND_COMPLETED	A refund reached a terminal outcome, regardless of how it was initiated (your POST /refunds call, the Simpler merchant dashboard, or the payment provider directly). Fires only once a refund is fully resolved or fully failed — not on intermediate "in progress" states.	SUCCEEDED, FAILED

ORDER_UPDATED status transitions

status	Fires when
PAYMENT_SUCCESS	Payment of an asynchronous method (MultiBanco, MBway, Sequra) was completed by the shopper. Not sent for synchronous methods (card, wallets) — those orders arrive at /submit with status: COMPLETED.
PAYMENT_FAILED	Payment could not be completed — e.g. a MultiBanco voucher expired unpaid after 72 hours, or a Sequra risk check rejected the shopper.

REFUND_COMPLETED outcome values

outcome	Fires when	reason
SUCCEEDED	The refund was confirmed by the payment provider (or independently confirmed already returned).	Absent.
FAILED	The refund could not be completed — e.g. the retry window for insufficient balance was exhausted, the payment provider rejected it outright, or it was cancelled.	Always present; a free-text explanation, not a stable enum.

No request correlation today

REFUND_COMPLETED does not echo back any identifier from your original POST /refunds call. Correlate the event with your local order/refund record using order_id — and amount_cents if you need to disambiguate between multiple partial refunds on the same order.

Payload shape

Every event delivery contains:

• The event envelope (type, created_at, data) — see order_updated.yml and refund_completed.yml via the OpenAPI reference.
• The X-Simpler-CRC signature header (HMAC-SHA1 of the raw body with your app secret).
• An Idempotency-Key HTTP header for dedup (see Retries & Timeouts).

See also

• Handling Webhooks tutorial — complete receiver implementation.
• Handling Refunds tutorial — issuing refunds and handling REFUND_COMPLETED.
• Retries & Timeouts — delivery retry schedule and idempotency handling.
• Order lifecycle — how webhook events map to order state on the partner side.