Receives and processes inbound webhook events from Paystack. This endpoint is not called by your app — it is called by Paystack’s servers.
Security: Every request is verified using HMAC-SHA512 against the
x-paystack-signature header. Requests with an invalid or missing signature
return 401 immediately.
Handled events:
| Event | Channel | Action |
|---|---|---|
charge.success | dedicated_nuban | Credit wallet. If metadata.purpose = escrow_charge and amount ≥ pending tx → lock escrow, activate, send invite. If amount < pending tx → credit wallet only, notify user of shortfall via WhatsApp. |
charge.success | card | Safety net only — card charges are synchronous so this is treated as idempotent. |
transfer.success | — | Mark escrow_release transaction as succeeded, update escrow → released. |
transfer.failed / transfer.reversed | — | Mark transaction as failed. Escrow status unchanged — requires support intervention. |
Always returns 200 for valid signatures, even if internal processing fails.
This prevents Paystack from retrying and causing duplicate wallet credits or
escrow activations. Errors are logged server-side.
Configure in Paystack dashboard:
Dashboard → Settings → API Keys & Webhooks → Webhook URL
Set to: {your_supabase_url}/functions/v1/webhook-paystack