Skip to content

refactor: unify webhook delivery pipeline and migrate to Redis #220

@ericfitz

Description

@ericfitz

Summary

Complete the webhook delivery unification started in #194. This issue covers Phases 2 and 3 of the design.

Design spec: docs/superpowers/specs/2026-03-29-webhook-delivery-unification-design.md

Background

Issue #194 (Phase 1) unified the addon invocation webhook payload and headers to match resource-change webhooks, and renamed invocation_id to delivery_id. This issue completes the convergence by building a unified Redis-backed delivery pipeline.

Design Decisions

  • All delivery state moves to Redis (replacing both Postgres webhook_deliveries and Redis AddonInvocation stores)
  • Any webhook delivery can use X-TMI-Callback: async for bidirectional status callbacks (not just addon invocations)
  • Addon invocations emit events to Redis Streams and flow through the same delivery worker as resource-change events
  • New GET /webhook-deliveries/{id} endpoint supports JWT or HMAC authentication
  • New POST /webhook-deliveries/{id}/status endpoint replaces POST /invocations/{id}/status

Redis TTLs

  • pending / in_progress: 4 hours
  • failed / completed / delivered: 7 days

Phase 2: Unified Redis Delivery Model + Migrate Addon Invocations

  • Create WebhookDeliveryRedisStore with unified delivery record
  • Add POST /webhook-deliveries/{id}/status endpoint (replaces POST /invocations/{id}/status)
  • Add GET /webhook-deliveries/{id} endpoint with JWT+HMAC dual auth (replaces GET /invocations/{id})
  • Remove GET /invocations list endpoint
  • Modify POST /addons/{id}/invoke to create unified delivery records and emit to Redis Streams
  • Remove AddonInvocationWorker and AddonInvocationStore
  • Route addon.invoked events through WebhookEventConsumer → unified delivery worker
  • Add X-TMI-Callback: async response handling to delivery worker
  • Update cleanup worker to handle unified deliveries
  • Update OpenAPI spec, tests, docs, wiki

Phase 3: Migrate Resource-Change Deliveries from Postgres to Redis

  • Repoint WebhookEventConsumer to create Redis delivery records instead of Postgres
  • Repoint admin endpoints (/admin/webhooks/deliveries/*) to read from Redis
  • Remove GormWebhookDeliveryStore and webhook_deliveries Postgres table
  • Add migration to drop the Postgres table
  • Update tests

Metadata

Metadata

Assignees

Labels

apiAPI design and implementation

Projects

Status

Done

Relationships

None yet

Development

No branches or pull requests

Issue actions