Event Reference
Full catalogue of webhook events Zertiban emits on every relevant state change.
Webhook events are the primary real-time sync mechanism between Zertiban and the customer's integrated systems. Every relevant change in the life cycle of a flow, an operation or a PSD2 payment automatically produces a signed webhook event, so external systems can react immediately without polling the API.
Webhook delivery must be enabled with Zertiban beforehand. During onboarding the customer must provide:
- The receiving HTTPS endpoint.
- The environment: Sandbox or Production.
- The webhook event types to subscribe to.
Once configured, Zertiban will push real-time notifications whenever a relevant state change occurs.
Functional event model
Zertiban's event system is organised in three functional layers, each covering a distinct layer of the transactional process:
| Level | Represents |
|---|---|
FLOW_* | Aggregate state of the full set of operations |
OPERATION_* | Individual actions taken by the end user |
PSD2_PAYMENT_* | Real banking state of the PSD2 payment |
Flow events
FLOW_* events represent the aggregate state of the full set of operations attached to a flow.
In most current integrations a flow holds a single operation, so flow events usually mirror that operation's outcome directly. That said, Zertiban's architecture is prepared to support multiple operations within the same flow.
| Event | When it is emitted |
|---|---|
| FLOW_IN_PROGRESS | At least one operation in the flow was opened |
| FLOW_COMPLETED | All operations in the flow completed successfully |
| FLOW_REJECTED | All operations were rejected |
| FLOW_EXPIRED | All operations expired |
| FLOW_CANCELLED | The flow was cancelled |
Operation events
OPERATION_* events reflect the functional state of an individual operation carried out by the end user. They let you monitor the payer's actual behaviour inside the flow and react in real time to functional changes in the process.
| Event | When it is emitted | Suggested action |
|---|---|---|
| OPERATION_OPENED | The payer opens the operation URL | Log the open or interaction start |
| OPERATION_COMPLETED | The operation completes successfully | Mark the invoice or charge as paid |
| OPERATION_REJECTED | The user or the bank rejects the operation | Notify the collections team |
| OPERATION_EXPIRED | The operation reaches its expiration date | Mark as overdue |
| OPERATION_CANCELLED | The operation is cancelled via API or Dashboard | Update internal state |
PSD2 payment events
PSD2_PAYMENT_* events represent the real banking state of a PSD2 payment processed by Zertiban. Unlike the functional flow or operation events, these events reflect the payment's banking evolution directly within the PSD2 infrastructure and allow syncing real financial states with ERPs, reconciliation systems or treasury engines.
They are emitted automatically as the payment progresses through the banking ecosystem and provide full visibility on the real financial state of the transaction.
| Event | When it is emitted | Suggested action |
|---|---|---|
| PSD2_PAYMENT_STATUS_PENDING | The payment was initiated and is pending | Log the payment as in progress |
| PSD2_PAYMENT_STATUS_AUTHORIZED | The bank authorised the payment successfully | Confirm bank authorisation |
| PSD2_PAYMENT_STATUS_SETTLED | The payment was settled successfully | Reconcile and close the charge |
| PSD2_PAYMENT_STATUS_PENDING_SETTLED | The payment is pending final settlement | Keep financial tracking active |
| PSD2_PAYMENT_STATUS_REJECTED | The payment was rejected | Handle the incident or retry |
Emission rules and idempotency
PSD2 events follow specific rules to avoid duplicates and guarantee functional consistency.
Event deduplication. Before emitting a PSD2 webhook, Zertiban verifies that no event has already been sent for the same payment and the same PSD2 status. This guarantees delivery idempotency and prevents functional duplicates.
Special restriction for rejected payments. The PSD2_PAYMENT_STATUS_REJECTED event is only emitted if the payment has previously reached a valid prior transactional state in its life cycle. This keeps the functional sequence of financial states consistent.
What does resource contain in each event?
The resource payload depends on the event type:
| Event type | Contents |
|---|---|
FLOW_* | Aggregate information about the flow |
OPERATION_* | Operation information |
PSD2_PAYMENT_* | PSD2 payment information |
Functional recommendations
Use PSD2 events for bank reconciliation
PSD2_PAYMENT_* events represent the real financial state of the payment and are the best source for bank reconciliation, ERP updates, treasury and financial automation.
Use OPERATION_COMPLETED for UX and business logic
The OPERATION_COMPLETED event represents the functional completion of the user experience and is typically used to release orders, mark invoices, show confirmations or advance business processes.
Idempotent webhook consumers
Every webhook consumer must be designed to tolerate retries, duplicate events and out-of-order delivery. Persist eventUuid and apply idempotent processing, see Delivery and Retries.
Recommended asynchronous processing
The webhook endpoint should verify the signature, persist the event, respond 200 OK and process in the background. This improves resilience and avoids unnecessary retries.