Webhook Management

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/webhook-management/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Developers can register webhooks to receive real-time notifications for order events (created, paid, shipped, cancelled), inventory events, and payment events. Webhooks are delivered with automatic retries, signature verification, and a delivery history UI. Core owns the webhook dispatcher; this is infrastructure, not a paid feature.

The problem

Developers need event notifications but cannot register webhooks; they poll the API constantly, wasting bandwidth and causing latency. Webhooks are essential for real-time integrations.

What it does

• Webhook registration: developers can create, list, edit, delete webhooks via API or admin UI
• Event types: supported events are order.created, order.paid, order.shipped, order.cancelled, inventory.changed, payment.failed
• Signed webhooks: each webhook is signed with HMAC-SHA256; developer can verify authenticity
• Retry logic: if webhook delivery fails (timeout, 5xx), retry up to 5 times with exponential backoff
• Delivery history: admin UI shows all webhook deliveries with status (success, failed, retrying)
• Manual retry: admin can manually retry failed webhooks
• Event filtering: developer can choose which events to receive (subscribe to order events only, etc.)
• Test webhook: admin can send test event to webhook URL

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Webhook queues: we deliver webhooks; buffering/batching is merchant’s responsibility.
• Conditional webhooks: we send all subscribed events; filtering by amount/country is merchant’s responsibility.
• Webhook templates: we send raw event JSON; formatting is developer’s responsibility.

Data model

New document: webhook { webhookId, url, events (array), active (boolean), createdAt, lastDeliveryAt }. New document: webhook_delivery { deliveryId, webhookId, eventType, payload, status (success, failed, retrying), statusCode, response, timestamp, nextRetryAt }.

API

• POST /api/webhooks { url, events } -> { webhookId, secret }
• GET /api/webhooks (auth required) -> list of merchant’s webhooks
• PUT /api/webhooks/{webhookId} { url, events, active } (auth required)
• DELETE /api/webhooks/{webhookId} (auth required)
• GET /api/webhooks/{webhookId}/deliveries (auth required, admin UI uses this)
• POST /api/webhooks/{webhookId}/retry/{deliveryId} (admin only, manual retry)
• POST /api/webhooks/test { webhookId, eventType } (admin only, sends test event)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Admin sees: webhook list (URL, events, active status), delivery history (event type, timestamp, status, response code), manual retry button, test webhook button.

The seam — why this is core

Core owns the webhook dispatcher, retry logic, signature verification, and delivery history. No paid seam; this is infrastructure.

Core owns the interface + honest webhook dispatcher; event delivery is infrastructure, not a support commitment or credential.

Dependencies

• event subsystem (existing; publishes events)
• authentication subsystem (existing; verifies API key)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Developer registers webhook for order.created and order.paid events; webhook receives both event types
• Order is created; webhook is delivered within 1 second with order details
• Webhook delivery fails (5xx); retry happens after 10s, 30s, 1m, 5m, 30m (exponential backoff)
• Webhook signature is HMAC-SHA256(payload, secret); developer can verify by hashing received payload
• Admin clicks ‘Send test event’; webhook receives test order.created event
• Admin views delivery history showing 100 successful, 2 failed (with response code), 1 retrying
• Admin manually retries failed delivery; webhook receives event again
• Webhook URL that is not HTTPS or times out is logged; delivery is marked failed

Risks

If webhook secret is logged unencrypted, attacker can forge webhooks. If signature verification is not enforced, merchant cannot trust webhook source. If retry logic is too aggressive, webhook service gets hammered. If delivery history is not stored, merchant cannot debug failed integrations. If webhook is sent to HTTP (not HTTPS), payload is intercepted. If retry consumes quota (rate limiting), merchant is blocked by retries.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.