Skip to main content

Webhook Dispatcher — Migration Plan

Status: populated Owner: Platform Engineering Last updated: 2026-04-18 Companion: DATA_MODEL · DEPLOYMENT_TOPOLOGY

1. Initial Bootstrap Migration (Greenfield)​

Flyway Migration Sequence​

VersionFileDescription
V1V1__create_hook_schema.sqlCreate hook schema
V2V2__create_webhook_configs.sqlhook.webhook_configs + indexes + max-10 trigger
V3V3__create_delivery_attempts.sqlhook.delivery_attempts + indexes
V4V4__add_delivery_status_check.sqlCHECK constraint on status enum values
V5V5__add_payload_snapshot_compression.sqlEnable TOAST compression on payload_snapshot
V6V6__grant_hook_svc.sqlGRANT statements for hook_svc service account

2. Deployment Checklist (New Environment)​

  • PostgreSQL hook schema created
  • Flyway V1–V6 applied successfully
  • hook_svc service account created with correct grants
  • KMS key provisioned and IAM role attached to pod service account
  • NATS stream WEBHOOK_DISPATCH created with correct retention (24 h)
  • Durable consumer webhook-dispatcher provisioned
  • Kong service + routes configured
  • JWT plugin configured with correct JWKS endpoint
  • Kubernetes Secrets populated (DATABASE_URL, NATS TLS, KMS)
  • ConfigMap applied
  • Deployment scaled to 3 replicas + HPA applied
  • Prometheus scrape target configured
  • Grafana dashboard imported
  • Alert rules applied and tested

3. Future Migration: Add Webhook Versioning​

When REST API v2 is introduced:

  1. Add api_version column to hook.webhook_configs (nullable, default v1).
  2. No data migration required; existing configs remain v1.
  3. New v2 features gated on api_version = 'v2'.

4. Future Migration: Add Webhook Signing Algorithm Field​

Allow per-webhook choice of signing algorithm (currently hardcoded HMAC-SHA256):

  1. Add signing_algorithm VARCHAR(16) NOT NULL DEFAULT 'HMAC-SHA256'.
  2. Existing webhooks default to current behaviour.
  3. New algorithms added as application feature, not schema migration.

5. Rollback Procedure​

  1. Scale webhook-dispatcher to 0 replicas.
  2. Restore previous image tag.
  3. If schema rollback needed: apply down-migration script.
  4. Scale to 3 replicas.
  5. Verify /ready returns 200; verify hook_nats_consumer_status = 1.
  6. Monitor retry poller for any stalled FAILED_RETRY rows.