@quickback-dev/cli 0.10.15 → 0.10.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (249) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +40 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.js +6 -6
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/skill/SKILL.md +142 -1051
  8. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  9. package/dist/skill/docs/changelog.md +1192 -0
  10. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  11. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  12. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  17. package/dist/skill/docs/compiler/config/agents.md +144 -0
  18. package/dist/skill/docs/compiler/config/auth.md +109 -0
  19. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  20. package/dist/skill/docs/compiler/config/domains.md +149 -0
  21. package/dist/skill/docs/compiler/config/index.md +419 -0
  22. package/dist/skill/docs/compiler/config/output.md +338 -0
  23. package/dist/skill/docs/compiler/config/providers.md +248 -0
  24. package/dist/skill/docs/compiler/config/security.md +255 -0
  25. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  26. package/dist/skill/docs/compiler/config/variables.md +157 -0
  27. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  28. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  29. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  30. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  31. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  32. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  33. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  34. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  36. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  37. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  38. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  39. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  40. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  41. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  42. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  43. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  44. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  45. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  46. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  47. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  48. package/dist/skill/docs/compiler/index.md +85 -0
  49. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  50. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  64. package/dist/skill/docs/compiler/targets/index.md +47 -0
  65. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  66. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  69. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  70. package/dist/skill/docs/index.md +77 -0
  71. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  72. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  73. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  74. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  75. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  76. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  77. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  78. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  79. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  80. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  81. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  82. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  83. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  85. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  86. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  87. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  88. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  89. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  90. package/dist/skill/docs/stack/auth/index.md +64 -0
  91. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  92. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  93. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  94. package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
  95. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  96. package/dist/skill/docs/stack/auth/security.md +455 -0
  97. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  98. package/dist/skill/docs/stack/cms/actions.md +199 -0
  99. package/dist/skill/docs/stack/cms/components.md +479 -0
  100. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  101. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  102. package/dist/skill/docs/stack/cms/index.md +158 -0
  103. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  104. package/dist/skill/docs/stack/cms/pages.md +275 -0
  105. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  106. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  107. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  108. package/dist/skill/docs/stack/cms/security.md +203 -0
  109. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  110. package/dist/skill/docs/stack/index.md +65 -0
  111. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  112. package/dist/skill/docs/stack/queues/index.md +56 -0
  113. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  114. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  115. package/dist/skill/docs/stack/realtime/index.md +67 -0
  116. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  117. package/dist/skill/docs/stack/storage/index.md +17 -0
  118. package/dist/skill/docs/stack/storage/kv.md +204 -0
  119. package/dist/skill/docs/stack/storage/r2.md +232 -0
  120. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  121. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  122. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  123. package/dist/skill/docs/stack/vector/index.md +44 -0
  124. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  125. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  126. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  127. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  128. package/package.json +1 -1
  129. package/src/skill/SKILL.md +142 -1051
  130. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  131. package/src/skill/docs/changelog.md +1192 -0
  132. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  133. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  134. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  135. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  136. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  137. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  138. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  139. package/src/skill/docs/compiler/config/agents.md +144 -0
  140. package/src/skill/docs/compiler/config/auth.md +109 -0
  141. package/src/skill/docs/compiler/config/bindings.md +176 -0
  142. package/src/skill/docs/compiler/config/domains.md +149 -0
  143. package/src/skill/docs/compiler/config/index.md +419 -0
  144. package/src/skill/docs/compiler/config/output.md +338 -0
  145. package/src/skill/docs/compiler/config/providers.md +248 -0
  146. package/src/skill/docs/compiler/config/security.md +255 -0
  147. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  148. package/src/skill/docs/compiler/config/variables.md +157 -0
  149. package/src/skill/docs/compiler/definitions/access.md +445 -0
  150. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  151. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  152. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  153. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  154. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  155. package/src/skill/docs/compiler/definitions/index.md +219 -0
  156. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  157. package/src/skill/docs/compiler/definitions/read.md +220 -0
  158. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  159. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  160. package/src/skill/docs/compiler/definitions/views.md +292 -0
  161. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  162. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  163. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  164. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  165. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  166. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  167. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  168. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  169. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  170. package/src/skill/docs/compiler/index.md +85 -0
  171. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  172. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  173. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  174. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  176. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  177. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  178. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  179. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  186. package/src/skill/docs/compiler/targets/index.md +47 -0
  187. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  188. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  189. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  191. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  192. package/src/skill/docs/index.md +77 -0
  193. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  194. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  195. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  196. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  197. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  198. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  199. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  200. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  201. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  202. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  203. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  204. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  205. package/src/skill/docs/stack/account-ui/index.md +147 -0
  206. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  207. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  208. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  209. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  210. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  211. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  212. package/src/skill/docs/stack/auth/index.md +64 -0
  213. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  214. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  215. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  216. package/src/skill/docs/stack/auth/plugins/index.md +228 -0
  217. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  218. package/src/skill/docs/stack/auth/security.md +455 -0
  219. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  220. package/src/skill/docs/stack/cms/actions.md +199 -0
  221. package/src/skill/docs/stack/cms/components.md +479 -0
  222. package/src/skill/docs/stack/cms/connecting.md +199 -0
  223. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  224. package/src/skill/docs/stack/cms/index.md +158 -0
  225. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  226. package/src/skill/docs/stack/cms/pages.md +275 -0
  227. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  228. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  229. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  230. package/src/skill/docs/stack/cms/security.md +203 -0
  231. package/src/skill/docs/stack/cms/table-views.md +142 -0
  232. package/src/skill/docs/stack/index.md +65 -0
  233. package/src/skill/docs/stack/queues/handlers.md +317 -0
  234. package/src/skill/docs/stack/queues/index.md +56 -0
  235. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  236. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  237. package/src/skill/docs/stack/realtime/index.md +67 -0
  238. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  239. package/src/skill/docs/stack/storage/index.md +17 -0
  240. package/src/skill/docs/stack/storage/kv.md +204 -0
  241. package/src/skill/docs/stack/storage/r2.md +232 -0
  242. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  243. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  244. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  245. package/src/skill/docs/stack/vector/index.md +44 -0
  246. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  247. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  248. package/src/skill/docs/stack/webhooks/index.md +36 -0
  249. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -0,0 +1,281 @@
1
+ # Outbound Webhooks
2
+
3
+ Outbound webhooks notify external services when events happen in your API. Users register webhook endpoints, subscribe to event types, and receive signed HTTP POST requests when events are emitted.
4
+
5
+ ## Overview
6
+
7
+ Outbound webhooks are a multi-step system:
8
+
9
+ 1. **Users register endpoints** via the REST API
10
+ 2. **Your code emits events** using `emitWebhookEvent()`
11
+ 3. **Quickback queues deliveries** for each matching endpoint
12
+ 4. **The queue consumer delivers** with retry and exponential backoff
13
+ 5. **Payloads are signed** with HMAC-SHA256 (Stripe-compatible format)
14
+
15
+ ## Emitting Events
16
+
17
+ Call `emitWebhookEvent()` in your actions or custom routes:
18
+
19
+ ```typescript
20
+ import { emitWebhookEvent } from '../lib/webhooks/emit';
21
+
22
+ // After creating a user
23
+ const newUser = await db.insert(users).values(data).returning();
24
+
25
+ await emitWebhookEvent(
26
+ "user.created",
27
+ newUser[0],
28
+ { organizationId: ctx.activeOrgId },
29
+ env
30
+ );
31
+ ```
32
+
33
+ **Parameters:**
34
+
35
+ | Parameter | Type | Description |
36
+ |-----------|------|-------------|
37
+ | `eventType` | `string` | Event name (e.g., `user.created`) |
38
+ | `payload` | `unknown` | Event data (auto-wrapped with metadata) |
39
+ | `options` | `object` | `{ organizationId?, userId? }` — scope for endpoint matching |
40
+ | `env` | `CloudflareBindings` | Cloudflare environment bindings |
41
+
42
+ **Note:** The compiler does NOT auto-emit events after CRUD operations. You must call `emitWebhookEvent()` explicitly where you want webhooks triggered.
43
+
44
+ ## Event Types
45
+
46
+ Quickback provides recommended event naming conventions:
47
+
48
+ | Category | Events |
49
+ |----------|--------|
50
+ | User | `user.created`, `user.updated`, `user.deleted` |
51
+ | Subscription | `subscription.created`, `subscription.updated`, `subscription.cancelled`, `subscription.renewed` |
52
+ | Organization | `organization.created`, `organization.updated`, `organization.deleted`, `organization.member_added`, `organization.member_removed` |
53
+ | File | `file.uploaded`, `file.deleted` |
54
+
55
+ You can emit any custom event type — these are conventions, not restrictions.
56
+
57
+ ## Payload Format
58
+
59
+ The emitted payload is wrapped automatically:
60
+
61
+ ```json
62
+ {
63
+ "type": "user.created",
64
+ "data": {
65
+ "id": "usr_abc123",
66
+ "name": "Jane Doe",
67
+ "email": "jane@example.com"
68
+ },
69
+ "createdAt": "2025-01-15T10:00:00.000Z"
70
+ }
71
+ ```
72
+
73
+ ## Payload Signing
74
+
75
+ Every delivery is signed with HMAC-SHA256 using the endpoint's secret. The signature format is Stripe-compatible:
76
+
77
+ ```
78
+ X-Webhook-Signature: t=1705312800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
79
+ ```
80
+
81
+ **Signed payload:** `<timestamp>.<json_body>`
82
+
83
+ **Additional headers:**
84
+
85
+ | Header | Description |
86
+ |--------|-------------|
87
+ | `X-Webhook-Signature` | `t=<timestamp>,v1=<hmac>` |
88
+ | `X-Webhook-Event` | Event type (e.g., `user.created`) |
89
+ | `X-Webhook-Delivery` | Delivery ID for tracking |
90
+ | `Content-Type` | `application/json` |
91
+
92
+ ### Verifying Signatures (Consumer Side)
93
+
94
+ ```typescript
95
+ import { createHmac, timingSafeEqual } from 'crypto';
96
+
97
+ function verifyWebhook(payload: string, signature: string, secret: string): boolean {
98
+ const [tPart, v1Part] = signature.split(',');
99
+ const timestamp = tPart.replace('t=', '');
100
+ const expectedSig = v1Part.replace('v1=', '');
101
+
102
+ // Check timestamp (5 minute tolerance)
103
+ const age = Date.now() / 1000 - parseInt(timestamp);
104
+ if (age > 300) return false;
105
+
106
+ const signed = `${timestamp}.${payload}`;
107
+ const computed = createHmac('sha256', secret).update(signed).digest('hex');
108
+ return timingSafeEqual(Buffer.from(computed), Buffer.from(expectedSig));
109
+ }
110
+ ```
111
+
112
+ ## Endpoint Management API
113
+
114
+ ### Register an Endpoint
115
+
116
+ ```
117
+ POST /webhooks/v1/endpoints
118
+ ```
119
+
120
+ ```json
121
+ {
122
+ "name": "My Integration",
123
+ "url": "https://example.com/webhook",
124
+ "events": ["user.created", "subscription.*"]
125
+ }
126
+ ```
127
+
128
+ **Response (201):**
129
+
130
+ ```json
131
+ {
132
+ "id": "wep_abc123",
133
+ "name": "My Integration",
134
+ "url": "https://example.com/webhook",
135
+ "secret": "whsec_a1b2c3d4...",
136
+ "events": ["user.created", "subscription.*"],
137
+ "enabled": true,
138
+ "createdAt": "2025-01-15T10:00:00.000Z"
139
+ }
140
+ ```
141
+
142
+ The `secret` is only returned on creation. Store it securely.
143
+
144
+ ### Event Pattern Matching
145
+
146
+ Endpoints subscribe to events using patterns:
147
+
148
+ | Pattern | Matches |
149
+ |---------|---------|
150
+ | `user.created` | Exact match only |
151
+ | `user.*` | All user events |
152
+ | `*` | All events |
153
+
154
+ ### Other Endpoints
155
+
156
+ | Method | Path | Description |
157
+ |--------|------|-------------|
158
+ | `GET` | `/webhooks/v1/endpoints` | List your endpoints |
159
+ | `GET` | `/webhooks/v1/endpoints/:id` | Get endpoint details (secret masked) |
160
+ | `PATCH` | `/webhooks/v1/endpoints/:id` | Update endpoint (name, url, events, enabled) |
161
+ | `DELETE` | `/webhooks/v1/endpoints/:id` | Delete endpoint |
162
+ | `GET` | `/webhooks/v1/endpoints/:id/deliveries` | List delivery attempts |
163
+ | `POST` | `/webhooks/v1/endpoints/:id/test` | Send a test event |
164
+ | `POST` | `/webhooks/v1/endpoints/:id/rotate-secret` | Generate a new signing secret |
165
+ | `GET` | `/webhooks/v1/events` | List available event types |
166
+
167
+ ### Access Control
168
+
169
+ Endpoints are scoped by `userId` or `organizationId`. Users can only manage their own endpoints. When emitting events, only endpoints matching the event's scope receive deliveries.
170
+
171
+ ### URL Validation (anti-SSRF)
172
+
173
+ Registered URLs are validated at registration and again before each delivery attempt. The default policy rejects:
174
+
175
+ - Any scheme other than `https:` (matches Stripe, GitHub, and Slack webhook conventions)
176
+ - Loopback hosts (`localhost`, `127.0.0.1`, `::1`)
177
+ - Cloud metadata endpoints (`169.254.169.254`, `metadata.google.internal`)
178
+ - RFC 1918 private ranges (`10/8`, `172.16/12`, `192.168/16`), `169.254/16`, and `0.0.0.0/8`
179
+ - Hosts ending in `.internal` or `.local`
180
+
181
+ Plaintext `http:` is rejected by default. To allow `http:` (e.g. for a self-hosted dev environment without TLS), set `webhookAllowInsecure: true` on the database provider config:
182
+
183
+ ```ts
184
+ // quickback.config.ts
185
+ providers: {
186
+ database: {
187
+ name: 'cloudflare-d1',
188
+ config: {
189
+ webhooksBinding: 'WEBHOOKS_DB',
190
+ webhookAllowInsecure: true, // dev/self-host only
191
+ },
192
+ },
193
+ }
194
+ ```
195
+
196
+ The other validation rules (private/loopback/metadata blocking) still apply when this flag is on.
197
+
198
+ ### Redirect Handling
199
+
200
+ Outbound delivery uses `redirect: "manual"` — the runtime refuses to follow 3xx responses. A redirect is treated as a **terminal** delivery failure (no retry), and the redirect target is recorded in the `responseBody`. This protects signed payloads from being bounced to a different host than the one the user registered.
201
+
202
+ If your endpoint legitimately needs to relocate, update the `url` on the endpoint record instead of relying on a 301/302.
203
+
204
+ ## Delivery and Retry
205
+
206
+ Deliveries are processed asynchronously via a Cloudflare Queue.
207
+
208
+ **Success:** HTTP 2xx response marks the delivery as `delivered`.
209
+
210
+ **Failure:** HTTP 4xx/5xx or network errors trigger retries with exponential backoff:
211
+
212
+ | Attempt | Delay |
213
+ |---------|-------|
214
+ | 1st retry | ~2 seconds |
215
+ | 2nd retry | ~4 seconds |
216
+ | 3rd retry (final) | ~8 seconds |
217
+
218
+ Maximum backoff is capped at 1 hour. After 3 failed attempts, the delivery is marked as `failed`.
219
+
220
+ **Disabled endpoints:** If an endpoint is disabled or deleted between emission and delivery, the delivery is marked as failed immediately.
221
+
222
+ ### Delivery Record
223
+
224
+ Each delivery attempt is tracked in the `webhook_deliveries` table:
225
+
226
+ | Field | Description |
227
+ |-------|-------------|
228
+ | `status` | `pending`, `delivered`, or `failed` |
229
+ | `attempts` | Number of delivery attempts |
230
+ | `responseStatus` | HTTP status from last attempt |
231
+ | `responseBody` | Response body (truncated to 1000 chars) |
232
+ | `lastAttemptAt` | Timestamp of last attempt |
233
+ | `nextRetryAt` | When the next retry will occur |
234
+
235
+ ## Infrastructure
236
+
237
+ ### Queue Configuration
238
+
239
+ Outbound webhooks use a dedicated Cloudflare Queue:
240
+
241
+ ```toml
242
+ # Auto-generated in wrangler.toml
243
+ [[queues.producers]]
244
+ queue = "my-app-webhooks-queue"
245
+ binding = "WEBHOOKS_QUEUE"
246
+
247
+ [[queues.consumers]]
248
+ queue = "my-app-webhooks-queue"
249
+ max_batch_size = 10
250
+ max_batch_timeout = 30
251
+ max_retries = 3
252
+ dead_letter_queue = "my-app-webhooks-dlq"
253
+ ```
254
+
255
+ ### Dead Letter Queue
256
+
257
+ Failed webhook deliveries (after all retries) are sent to a dead letter queue for investigation:
258
+
259
+ ```toml
260
+ [[queues.consumers]]
261
+ queue = "my-app-webhooks-dlq"
262
+ max_batch_size = 1
263
+ ```
264
+
265
+ ## Enabling Webhooks
266
+
267
+ Set `webhooksBinding` in your database provider config:
268
+
269
+ ```typescript
270
+ database: defineDatabase("cloudflare-d1", {
271
+ binding: "DB",
272
+ webhooksBinding: "WEBHOOKS_DB",
273
+ })
274
+ ```
275
+
276
+ This generates the webhook database schema, routes, queue consumer, and all supporting code.
277
+
278
+ ## See Also
279
+
280
+ - [Inbound Webhooks](/stack/webhooks/inbound) — Receive webhooks from external services
281
+ - [Queues](/stack/queues) — Background processing infrastructure
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.10.15",
3
+ "version": "0.10.20",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",