Merge pull request #37 from totte-dev/release/v0.4.1

Release v0.4.1: Outbound webhooks

Author: ezqy

CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-03-11
+
+### Added
+- **Outbound webhooks**: Send webhooks to your customers with per-endpoint HMAC-SHA256 signatures. New `type: outbound` source with dynamic endpoint management via REST API.
+  - `POST/GET /api/outbound/endpoints` — create and list customer endpoints
+  - `GET/PUT/DELETE /api/outbound/endpoints/:id` — manage individual endpoints
+  - `POST /api/outbound/endpoints/:id/rotate-secret` — rotate signing secret
+  - `POST/GET/DELETE /api/outbound/endpoints/:id/subscriptions` — event type subscriptions
+  - Per-endpoint signing secret (`whsec_` prefix) with `X-Qhook-Signature: v1=<hmac>` and `X-Qhook-Timestamp` headers
+  - Wildcard (`*`) subscriptions, fan-out to multiple endpoints, disable/enable toggle
+  - Reuses existing retry, DLQ, and circuit breaker infrastructure
+- **Example**: `examples/outbound-webhook/` — customer webhook receiver with signature verification
+- 10 outbound E2E tests + 1 full lifecycle scenario test (endpoint → subscribe → deliver → verify signature → disable → rotate secret)
+- TypeScript and Python SDK generation from OpenAPI spec (`sdks/generate.sh`)
+
 ## [0.4.0] - 2026-03-11
 
 ### Added

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "qhook"
-version = "0.4.0"
+version = "0.4.1"
 edition = "2024"
 rust-version = "1.85"
 description = "Lightweight webhook gateway and workflow engine with queue, retry, and signature verification."

examples/outbound-webhook/README.md

@@ -0,0 +1,71 @@
+# Outbound Webhooks
+
+Send webhooks to your customers with HMAC-SHA256 signatures. Like Svix, but built into qhook.
+
+## Setup
+
+1. Start qhook:
+
+```bash
+qhook start -c examples/outbound-webhook/qhook.yaml
+```
+
+2. Register a customer endpoint:
+
+```bash
+curl -s -X POST http://localhost:8888/api/outbound/endpoints \
+  -H "Authorization: Bearer my-secret-token" \
+  -H "Content-Type: application/json" \
+  -d '{"source": "my-saas", "url": "http://localhost:9000/webhook", "description": "Customer A"}'
+```
+
+Save the `signing_secret` from the response (starts with `whsec_`).
+
+3. Subscribe the endpoint to events:
+
+```bash
+curl -s -X POST http://localhost:8888/api/outbound/endpoints/{ENDPOINT_ID}/subscriptions \
+  -H "Authorization: Bearer my-secret-token" \
+  -H "Content-Type: application/json" \
+  -d '{"event_types": ["order.created", "payment.completed"]}'
+```
+
+4. Start the customer receiver (pass the signing secret):
+
+```bash
+python3 examples/outbound-webhook/receiver.py whsec_...
+```
+
+5. Send an event from your app:
+
+```bash
+curl -X POST http://localhost:8888/events/my-saas/order.created \
+  -H "Authorization: Bearer my-secret-token" \
+  -H "Content-Type: application/json" \
+  -d '{"order_id": "ord_001", "customer": "alice", "amount": 4999}'
+```
+
+## Expected Output
+
+The customer receiver logs:
+
+```
+[VERIFIED] event_type=order.created event_id=01JXXXX delivery_id=01JYYYY payload={"order_id": "ord_001", "customer": "alice", "amount": 4999}
+```
+
+## What This Shows
+
+- **Dynamic endpoint registration** via Management API
+- **Per-endpoint signing secrets** with `whsec_` prefix
+- **HMAC-SHA256 signed delivery** with `X-Qhook-Signature: v1=...`
+- **Subscription-based routing** -- only subscribed event types are delivered
+- **Automatic retry** with exponential backoff on failure
+
+## Management API
+
+| Operation | Command |
+|-----------|---------|
+| List endpoints | `curl -H "Authorization: Bearer $TOKEN" http://localhost:8888/api/outbound/endpoints` |
+| Disable endpoint | `curl -X PUT -H "Authorization: Bearer $TOKEN" -d '{"status":"disabled"}' http://localhost:8888/api/outbound/endpoints/{id}` |
+| Rotate secret | `curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8888/api/outbound/endpoints/{id}/rotate-secret` |
+| Delete endpoint | `curl -X DELETE -H "Authorization: Bearer $TOKEN" http://localhost:8888/api/outbound/endpoints/{id}` |

examples/outbound-webhook/qhook.yaml

@@ -0,0 +1,14 @@
+# Outbound webhook example -- send webhooks to your customers
+database:
+  driver: sqlite
+
+server:
+  port: 8888
+  allow_private_urls: true
+
+api:
+  auth_token: ${QHOOK_API_TOKEN:-my-secret-token}
+
+sources:
+  my-saas:
+    type: outbound

examples/outbound-webhook/receiver.py

@@ -0,0 +1,62 @@
+"""
+Customer webhook receiver that verifies qhook signatures.
+Demonstrates how your customers verify outbound webhook deliveries.
+No dependencies beyond Python stdlib.
+"""
+from http.server import HTTPServer, BaseHTTPRequestHandler
+import hashlib
+import hmac
+import json
+import sys
+
+
+# Set this to the signing_secret returned when creating the endpoint
+SIGNING_SECRET = sys.argv[1] if len(sys.argv) > 1 else ""
+
+
+class Handler(BaseHTTPRequestHandler):
+    def do_POST(self):
+        length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(length)
+
+        # Extract signature headers
+        signature = self.headers.get("X-Qhook-Signature", "")
+        timestamp = self.headers.get("X-Qhook-Timestamp", "")
+        event_type = self.headers.get("X-Qhook-Event-Type", "")
+        event_id = self.headers.get("X-Qhook-Event-ID", "")
+        delivery_id = self.headers.get("X-Qhook-Delivery-ID", "")
+
+        # Verify signature
+        verified = False
+        if SIGNING_SECRET and signature.startswith("v1="):
+            expected = hmac.new(
+                SIGNING_SECRET.encode(),
+                f"{timestamp}.".encode() + body,
+                hashlib.sha256,
+            ).hexdigest()
+            verified = hmac.compare_digest(signature[3:], expected)
+
+        payload = json.loads(body) if body else {}
+        status = "VERIFIED" if verified else ("UNVERIFIED" if SIGNING_SECRET else "NO_SECRET")
+
+        print(f"[{status}] event_type={event_type} event_id={event_id} "
+              f"delivery_id={delivery_id} payload={json.dumps(payload)}")
+
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(b'{"status":"ok"}')
+
+    def log_message(self, format, *args):
+        pass  # suppress default access logs
+
+
+if __name__ == "__main__":
+    port = 9000
+    server = HTTPServer(("0.0.0.0", port), Handler)
+    print(f"Customer webhook receiver listening on :{port}")
+    if SIGNING_SECRET:
+        print(f"Verifying signatures with secret: {SIGNING_SECRET[:12]}...")
+    else:
+        print("No signing secret provided -- pass it as: python3 receiver.py whsec_...")
+    server.serve_forever()