[Phase 1] Webhook Infrastructure & Delivery Guarantees

[syed-reza98]

Priority: P0 (Critical)

Phase: 1 - E-Commerce Core
Estimate: 3 days
Type: Story

Context

Provide outbound webhooks for key domain events (order.created, payment.completed, inventory.low, product.updated) with retry, idempotency, signature verification, and delivery metrics.

Scope

• WebhookEndpoint (id, organizationId, url, secret, active, eventTypes[], failureCount, lastSuccessAt)
• WebhookDelivery (id, endpointId, eventType, status, attempt, responseCode, nextAttemptAt, createdAt)
• Event dispatcher utility invoked post-transaction commit
• Retry policy: exponential backoff (1m, 5m, 30m, 2h, 24h) max 6 attempts
• HMAC signature header X-StormCom-Signature (SHA-256 using secret + body)
• Delivery filtering by subscribed event types

Acceptance Criteria

• Endpoint can subscribe to subset of events
• Failed delivery retried per schedule until success or max attempts
• Idempotent: same event sent once per endpoint (no duplicates) unless retried
• Signature verified by consumer example script (documented)
• Metrics: delivery.success.count, delivery.failure.count, delivery.latency.p95
• Admin can deactivate endpoint preventing future dispatch

Data Model (Draft)

model WebhookEndpoint {
  id             String    @id @default(cuid())
  organizationId String
  url            String
  secret         String
  eventTypes     String[] // Postgres text[] later
  active         Boolean   @default(true)
  failureCount   Int       @default(0)
  lastSuccessAt  DateTime?
  createdAt      DateTime  @default(now())
  updatedAt      DateTime  @updatedAt

  @@index([organizationId])
}

model WebhookDelivery {
  id           String   @id @default(cuid())
  endpointId   String
  eventType    String
  status       DeliveryStatus @default(PENDING)
  attempt      Int      @default(1)
  responseCode Int?
  nextAttemptAt DateTime?
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt

  @@index([endpointId])
  @@index([status])
}

enum DeliveryStatus {
  PENDING
  SUCCESS
  FAILED
  RETRYING
  ABANDONED
}

Dependencies

• Requires reliable event emission from payment/order/inventory changes
• Integrates with Idempotency layer ([Phase 1] Idempotency Key & Request Replay Safety Layer #66) for internal duplicate prevention

Metrics Targets

• Successful first-attempt rate > 95%
• Average delivery latency < 2s

Testing Checklist

• Mock endpoint receives order.created with valid signature
• Failure sequence triggers scheduled retries
• Deactivated endpoint receives no events

Risk

External integration reliability & partner trust (score: 16). Foundation for ecosystem expansion.

References

• docs/GITHUB_ISSUES_COMPARISON_ANALYSIS.md (webhook gap section)