Webhooks & Integration

Inbound Bounce Ingestion

⚡ Interactive Webhook Simulator

Test HMAC-SHA256 signature verification & SKIP LOCKED worker live from your browser

Live Sandbox

API Specification & Verification Pattern

# 1. Sign the exact raw request bytes with your tenant HMAC secret:
BODY='{"userId":"<uuid>","email":"a@b.com","type":"hard","reason":"550 5.1.1","eventId":"evt_123"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -r | cut -d' ' -f1)

# 2. Fire bounce webhook to ingestion endpoint:
curl -X POST http://localhost:3001/api/webhooks/bounce \
  -H "X-Bounce-Signature: $SIG" \
  -H 'Content-Type: application/json' \
  -d "$BODY"

# Returns HTTP 202 Accepted: {"ok":true,"queued":true}
# Replaying the exact same eventId will abort atomically without moving the score.

Queue & Concurrency Isolation

Bounces are never processed inline. The API returns 202 immediately and queues BounceEvent PENDING. The background worker drains rows using PostgreSQL FOR UPDATE SKIP LOCKED, guaranteeing zero lock contention across workers.

Strict Transactional Idempotency

Bounce.eventId @unique insert shares a single transaction with lead status updates and score increments. Duplicate deliveries roll back whole without moving the Hygiene Score (100 → 90 once, never twice).