Overview
The platform exposes three inbound webhook endpoints, each called by an external provider — not by your app. These are the mechanism by which payment confirmations and KYC results flow into the platform asynchronously.| Endpoint | Caller | Purpose |
|---|---|---|
POST /webhook-paystack | Paystack | Payment events — charges, transfers, virtual account assignment |
POST /webhook-sumsub | Sumsub | KYC review results for Tier 1–2 verification |
POST /webhook-youverify | Youverify | Identity check results for Tier 3+ verification |
Paystack webhook
Endpoint:POST /webhook-paystack
Signature verification: HMAC-SHA512 of the raw request body, compared against the x-paystack-signature header using your PAYSTACK_WEBHOOK_SECRET. Requests with an invalid or missing signature are rejected with 401.
Events handled
| Event | What it does |
|---|---|
charge.success (card top-up) | Marks the pending wallet top-up transaction as succeeded |
charge.success (DVA bank transfer) | Credits the user’s wallet and activates the escrow if fully funded |
charge.success (escrow_charge) | Locks escrow funds, activates escrow, sends invite to counterparty |
transfer.success | Marks the withdrawal or payout transaction as succeeded; moves escrow to released |
transfer.failed / transfer.reversed | Reverses the wallet deduction for failed withdrawals; marks escrow payout as failed |
dedicatedaccount.assign.success | Marks the virtual account as active |
dedicatedaccount.assign.failed | Marks the virtual account as inactive so the user can retry |
Partial DVA deposits
If a bank transfer to a virtual account is less than the escrow’s required amount, the received amount is credited to the wallet but the escrow stays indraft. The user is notified via WhatsApp of the shortfall and must fund the remaining balance.
Always return 200
Paystack retries events on any non-2xx response. The webhook handler always returns200 { received: true } for valid, processed events — even if an internal step fails — to prevent duplicate processing.
Sumsub webhook
Endpoint:POST /webhook-sumsub
Signature verification: HMAC-SHA512 digest of the raw body, compared against the x-payload-digest header. Register your SUMSUB_WEBHOOK_SECRET in the Sumsub dashboard.
Events handled
| Event | What it does |
|---|---|
applicantReviewed (GREEN) | Records a passed KYC check; triggers tier upgrade evaluation |
applicantReviewed (RED) | Records a failed KYC check with rejection labels |
Tier upgrade
When a review passes,evaluateAndUpgradeTier runs automatically — no polling or manual intervention is needed. If all checks required for the next tier have passed, the user’s KYC tier is upgraded immediately.
Youverify webhook
Endpoint:POST /webhook-youverify
Signature verification: Timing-safe comparison of the x-youverify-webhook-token header against your YOUVERIFY_WEBHOOK_SECRET.
Events handled
Youverify sends one event per verification type. The platform maps these to internal check types:Youverify verificationType | Internal check type |
|---|---|
NIN | nin |
BVN | bvn |
CAC | cac |
TIN | tin |
BANK_ACCOUNT | bank_account |
DIRECTOR | director_match |
status: "found" result is treated as passed. Any other status is recorded as a failed check. Tier upgrade evaluation runs automatically on a pass.
Registering webhooks
Configure each provider’s webhook URL in their respective dashboards:| Provider | Dashboard | URL to register |
|---|---|---|
| Paystack | Settings → Webhooks | https://<project>.supabase.co/functions/v1/webhook-paystack |
| Sumsub | Applicant Actions → Webhooks | https://<project>.supabase.co/functions/v1/webhook-sumsub |
| Youverify | Developer → Webhooks | https://<project>.supabase.co/functions/v1/webhook-youverify |