Webhook Handling

FINCI uses webhooks to notify the integrator about time-sensitive and operationally important events.

Webhooks are part of the platform event model for authorization and transaction processing. In integrator-managed decisioning setups, they are also part of the transaction decision path.

Primary webhook responsibilities

The integrator should be prepared to:

• receive authorization requests in real time
• where integrator-managed decisioning is used, decide whether to approve or decline
• receive the final authorization advice outcome
• process transaction lifecycle updates
• handle duplicate delivery safely

Authorization webhook expectations

In integrator-managed decisioning setups, authorization webhooks require a decision from the integrator.

In that model, the integrator must respond within 3 seconds. If FINCI does not receive a valid response within that timeout window, the transaction is declined.

The Authorization Flow guide defines the request-versus-advice message pattern and the meaning of advice and response_code.

That means the authorization handler should:

• avoid slow downstream dependencies where possible
• apply deterministic approval rules
• fail safely when balance or policy checks cannot complete in time

Webhook endpoint trust

FINCI sends webhooks only to endpoints that have been registered for the integration.

Webhook ingress should therefore enforce the expected environment and endpoint boundaries:

• only registered endpoints should receive webhook traffic
• sandbox and production endpoint configuration must remain separate
• source validation and network controls should reject unexpected traffic before business processing begins

Webhook endpoints should be dedicated, monitored, and protected as payment-critical interfaces.

Webhook consumer design

A practical implementation usually splits webhook handling into two layers:

1. a fast ingress layer that validates, records, and routes the event
2. business logic that decides or processes the event safely

For integrator-managed authorization decisions, those layers still need to fit within the 3-second timeout window.

For advice, presentment, reversal, and similar follow-up events, the integration should still persist the event durably and process it idempotently even when the business handling is asynchronous.

Idempotency and retries

Webhook consumers must be idempotent.

The same event may be delivered more than once, especially during retries or transient failures. The integrator should be able to identify duplicate processing attempts and avoid double booking or double state transitions.

The default delivery behavior reflected in this portal is:

• authorization decision requests require a valid response within 3 seconds
• follow-up authorization correction, reversal, and presentment deliveries may be retried every 60 seconds
• the maximum retry count is 10 attempts

Retry handling should be validated during onboarding and testing.

Use the Webhook Events reference for the exact event payloads and response schemas.

Use API Authentication for outbound Card API request signing.