Webhooks: Circle webhook handler (/webhooks/circle)

[manoahLinks]

Summary

Handle Circle webhooks for wallet/transaction lifecycle events. Circle is the source of truth for Circle-originated transactions — once this lands, on-chain RPC polling (#38) is only needed for externally-initiated mints.

Scope

• Route: `POST /webhooks/circle`
• Verify signature per Circle's signing scheme (defer to `circle:use-developer-controlled-wallets` for the exact header name + algorithm — do not inline).
• Whitelist source IPs if Circle publishes them.
• Match payload `transactionId` → `BlockchainTransaction.circleTransactionId`.
• Dispatch per event type (handler pattern):
  • Inbound USDC deposit → trigger pending ticket-mint (if tied to a ticket purchase)
  • Outbound transfer confirmed → mark payout `completed`, email organizer
  • Contract execution confirmed → update domain record (ticket status, check-in, etc.)
  • Contract execution failed → surface to dead-letter queue + alert
• Always respond 200 OK immediately, process async via Bull queue.
• Log every raw webhook payload for audit (24h retention minimum).

Acceptance criteria

• Signature verification test covers valid + invalid payloads
• Replay-safe (same `transactionId` processed twice is a no-op)
• All event types dispatched to correct handler
• Raw payload persisted to audit table
• Bull queue picks up dispatched work; retries on transient failure

Depends on

• Circle: SDK setup + entity secret registration + wallet set bootstrap #61 (SDK setup)
• DB: Prisma migration — add Circle wallet fields to users + blockchain_transactions #62 (Prisma fields — `circleTransactionId`)