Webhooks for integrations

• General description
  • Webhook Interaction Flow with External Providers
• Business Events That Trigger Webhooks
  • KYC Events
  • Payment and Gate Transaction Events
• Operational Visibility and Control

General description

Webhook functionality in SDK.finance provides a standard, event-driven way to integrate the platform with external KYC and payment providers without modifying the SDK.finance source code.

SDK.finance emits webhook notifications when key business events occur in the system. External systems subscribe to these events and process them.

This model allows SDK.finance to remain provider-agnostic while giving partners full flexibility to implement their own integration logic outside the platform. Webhooks are especially effective for scenarios where SDK.finance initiates a process, but execution and decision-making are handled by an external system.

Reliable delivery is ensured by the Webhook Dispatcher, which manages event creation, secure delivery, retries, and status tracking. Each business event is stored and fully traceable, providing operational transparency and confidence that external systems receive all required signals

Webhook Interaction Flow with External Providers

The interaction between SDK.finance and an external provider via webhooks follows a clear and predictable flow:

1. A business event occurs inside SDK.finance (for example, a KYC status change or creation of a payment transaction).

2. SDK.finance creates a webhook notification with a unique identifier and an initial delivery status.

3. The Webhook Dispatcher builds and signs an HTTP request and sends it to the configured external endpoint.

4. The external system (middleware, payment provider, or KYC provider) validates the webhook, processes the event, and performs the required action.

5. Based on the HTTP response, SDK.finance updates the notification status to delivered or schedules a retry according to the retry policy.

6. All delivery attempts and final outcomes remain visible and auditable in the system.

This interaction scheme allows SDK.finance to trigger external processing reliably, while external systems stay fully decoupled and can scale or change independently.

Business Events That Trigger Webhooks

SDK.finance sends webhook notifications only for clearly defined business events. These events represent meaningful state changes in the platform and are intended to be consumed by external systems.

KYC Events

When an organisation reaches the stage where an external KYC verification must be performed, SDK.finance sends a webhook notification indicating that a KYC check is required. This allows an external KYC provider or middleware to start the verification process without polling the platform or embedding provider-specific logic into SDK.finance.

Event sent:

• kyc_check_required — triggered when the organisation’s KYC status changes to pending and an external KYC provider is configured.

Payment and Gate Transaction Events

For integrations with external or custom gate providers, SDK.finance emits webhook events as soon as a gate top-up or withdrawal transaction is initiated. These events notify external systems that further processing is required outside of the platform.

Events sent:

• gate_topup_initiated — triggered when a gate top-up transaction is created

• gate_withdrawal_initiated — triggered when a gate withdrawal transaction is created

This enables payment providers or middleware layers to continue processing the transaction and later synchronise the result back to SDK.finance.

Operational Visibility and Control

All webhook notifications generated by SDK.finance are stored and can be reviewed by administrators. The platform provides visibility into what events were sent, when they were sent, and whether delivery was successful. Notifications can be filtered by event type, delivery status, webhook configuration, or related business entity, which simplifies monitoring, troubleshooting, and operational support.