Webhooks: Blockradar webhook handler (NGN virtual account deposits only)

[manoahLinks]

Status

RESCOPED 2026-04-24. All Circle-originated transaction webhooks now route through #65. This handler is retained only for Blockradar virtual-account NGN deposits.

Summary

Handle Blockradar webhooks for NGN virtual account deposits — the only Blockradar flow HostIT still uses (see #29). cNGN is minted on deposit and delivered to the linked Circle wallet address.

Events in scope

• `deposit.processing` — bank transfer received, cNGN minting
• `deposit.success` — cNGN minted + delivered to linked address
• `deposit.failed` / `deposit.cancelled` — log + alert organizer

Events explicitly out of scope (routed to #65 via Circle)

• ❌ Non-virtual-account deposits
• ❌ Withdrawals / transfers
• ❌ Gateway events
• ❌ Swap events

Implementation

• Route: `POST /webhooks/blockradar`
• Signature: `x-blockradar-signature` header, HMAC-SHA512(JSON.stringify(body), `BLOCKRADAR_API_KEY`)
• Match payload's linked address → Organizer via `circleWalletAddress`
• On `deposit.success`:
  • Persist cNGN balance increment to organizer's wallet-balance view
  • Notify organizer (in-app + email)
  • Emit audit event
• Return 200 OK immediately; process async via Bull queue.
• Retry-safe (idempotent on `transactionHash`).

Acceptance criteria

• Valid signature → 200 + queued job
• Invalid signature → 401 + alert
• Replay of same deposit hash → no-op
• Non-virtual-account event types → ignored + logged
• Dead-letter queue for malformed payloads

Depends on

• Payments: Blockradar provider (NGN virtual accounts only) #29 (virtual account provider implementation)
• DB: Prisma migration — add Circle wallet fields to users + blockchain_transactions #62 (Circle wallet fields for address linking)