Skip to content

feat(webhooks): outbound signed webhook notifications (working prototype) - #1098

Open
ritvik-jentic wants to merge 16 commits into
mainfrom
webhooks-outbound-poc
Open

ritvik-jentic wants to merge 16 commits into
mainfrom
webhooks-outbound-poc

Conversation

@ritvik-jentic

@ritvik-jentic ritvik-jentic commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

Working prototype — for review, not merge-ready. This is functional end to end (verified locally: real platform events flowed through to a Slack relay), but it is not yet fully polished or hardened. Expect rough edges in UX polish, and note that the relayed payload for many event types currently carries only minimal data.

Summary

This implements Approach 1: outbound signed webhooks + relay model.

  • Emits internal platform events and relays them into a durable delivery queue.
  • Signs each payload with HMAC-SHA256 using Standard Webhooks headers and POSTs to customer-owned endpoints.
  • Delivery is resilient: retry/backoff, dead-lettering, and auto-disable on 410 Gone.
  • Per-endpoint signing secrets are stored AES-256-GCM encrypted with rotation + a grace period during which the previous secret still verifies.

What's included

  • Backend delivery engine — event fan-out, durable queue, signer, and delivery worker (shared/webhooks/*, admin/services/webhooks/*).
  • DB tables + migration — webhook endpoints / events / deliveries (a1b2c3d4e5f7_add_webhook_tables).
  • Management API + permissions — endpoint CRUD/rotate/test/deliveries router guarded by webhooks:read / webhooks:write, plus audit targets and app-factory lifespan wiring.
  • UI management page + relay guide — event-type picker (descriptions + needs-action badge), delivery log, secret reveal/rotate dialogs, and an in-product relay guide.
  • Tests — signing (unit) plus integration for delivery, relay, the endpoint service, management HTTP, and secret storage.

Test plan

  • make lint (ruff + mypy) passes
  • uv run detect-secrets shows no new findings
  • Signing unit tests pass
  • Delivery / relay / endpoint-service / management-HTTP / secrets integration tests pass
  • UI webhooks page tests pass
  • Manual: create endpoint, trigger an event, confirm signed POST is received and verifies (locally verified via Slack relay)

Made with Cursor

ritvik-jentic and others added 2 commits August 19, 2026 17:38
…ype)

Emit internal platform events and relay them into a durable delivery queue.
Each payload is signed HMAC-SHA256 with Standard Webhooks headers and POSTed to
customer-owned endpoints with retry/backoff, dead-lettering, and auto-disable on
410 Gone. Signing secrets are stored per-endpoint with AES-256-GCM encryption and
support rotation with a grace period during which the previous secret still
verifies.

Adds an endpoint management surface: CRUD/rotate/test/deliveries router guarded by
webhooks:read / webhooks:write permissions, audit targets, and app-factory
lifespan wiring for the delivery worker. The UI ships a webhooks management page
with an event-type picker (descriptions + needs-action badge), a delivery log,
secret reveal/rotate dialogs, and an in-product relay guide.

Tests cover signing (unit) plus integration for delivery, relay, the endpoint
service, management HTTP, and secret storage.

This is a working prototype (Approach 1: raw signed webhook + relay) — functional
end to end but not yet fully polished or hardened.

Co-authored-by: Cursor <cursoragent@cursor.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant