webhook

name	webhook
description	Webhook design, delivery, retry, HMAC verification, event subscriptions, dead letter queues.

Webhook -- Design, Delivery & Security

Activate When

• /godmode:webhook, "write a webhook", "webhook handler"
• "webhook delivery", "callback URL"
• "verify webhook signature", "retry failed webhooks"
• "dead letter queue", "event notifications"
• When API needs to notify external systems

Workflow

Step 1: Discovery

# Detect webhook libraries and patterns
grep -r "svix\|standardwebhooks\|hmac\|createHmac" \
  package.json src/ --include="*.ts" -l 2>/dev/null
grep -r "webhook" --include="*.sql" \
  --include="*.prisma" -l 2>/dev/null
# Check queue integration
grep -r "BullMQ\|bull\|celery\|SQS\|amqplib" \
  package.json 2>/dev/null

WEBHOOK DISCOVERY:
Direction: Inbound | Outbound | Both
Events: <list event types>
Volume: <events/sec, daily total>
Latency SLA: <max delay>
Delivery: At-least-once | Best-effort
Auth: HMAC-SHA256 | mTLS | bearer token

IF inbound only: skip delivery system (Step 4)
IF outbound only: skip inbound handler (Step 3)
IF volume > 1000/sec: add partitioned queue
IF volume < 10/min: simple async dispatch OK

Step 2: Event & Payload Design

NAMING: <resource>.<past_tense_verb>
  e.g., order.created, payment.completed

ENVELOPE:
  id: evt_<ULID> (unique, sortable)
  type: resource.verb
  api_version: 2025-01-15
  created_at: ISO 8601 UTC
  data: { object: {...}, previous_attributes: {} }
  livemode: true|false

RULES:
  Max payload: 64KB
  Monetary values: cents (integer)
  Timestamps: ISO 8601 UTC
  NEVER include PII or secrets in payloads
  IF payload > 64KB: send reference + fetch URL
  WHEN previous state needed: include diff