@quickback-dev/cli 0.10.16 → 0.11.0
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.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +40 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +15 -10
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/skill/SKILL.md +142 -1051
- package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/dist/skill/docs/changelog.md +1225 -0
- package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
- package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/dist/skill/docs/compiler/config/agents.md +144 -0
- package/dist/skill/docs/compiler/config/auth.md +109 -0
- package/dist/skill/docs/compiler/config/bindings.md +176 -0
- package/dist/skill/docs/compiler/config/domains.md +149 -0
- package/dist/skill/docs/compiler/config/index.md +419 -0
- package/dist/skill/docs/compiler/config/output.md +338 -0
- package/dist/skill/docs/compiler/config/providers.md +248 -0
- package/dist/skill/docs/compiler/config/security.md +255 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
- package/dist/skill/docs/compiler/config/variables.md +157 -0
- package/dist/skill/docs/compiler/definitions/access.md +445 -0
- package/dist/skill/docs/compiler/definitions/actions.md +884 -0
- package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
- package/dist/skill/docs/compiler/definitions/feature.md +164 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
- package/dist/skill/docs/compiler/definitions/guards.md +241 -0
- package/dist/skill/docs/compiler/definitions/index.md +219 -0
- package/dist/skill/docs/compiler/definitions/masking.md +241 -0
- package/dist/skill/docs/compiler/definitions/read.md +220 -0
- package/dist/skill/docs/compiler/definitions/schema.md +697 -0
- package/dist/skill/docs/compiler/definitions/validation.md +35 -0
- package/dist/skill/docs/compiler/definitions/views.md +292 -0
- package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/dist/skill/docs/compiler/getting-started/index.md +192 -0
- package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
- package/dist/skill/docs/compiler/index.md +85 -0
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/dist/skill/docs/compiler/targets/index.md +47 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/dist/skill/docs/compiler/troubleshooting.md +120 -0
- package/dist/skill/docs/index.md +77 -0
- package/dist/skill/docs/stack/account-ui/customization.md +378 -0
- package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
- package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
- package/dist/skill/docs/stack/account-ui/index.md +147 -0
- package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
- package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/dist/skill/docs/stack/account-ui/worker.md +362 -0
- package/dist/skill/docs/stack/auth/api-keys.md +15 -0
- package/dist/skill/docs/stack/auth/device-auth.md +14 -0
- package/dist/skill/docs/stack/auth/index.md +64 -0
- package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +340 -0
- package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/dist/skill/docs/stack/auth/security.md +455 -0
- package/dist/skill/docs/stack/auth/using-auth.md +39 -0
- package/dist/skill/docs/stack/cms/actions.md +199 -0
- package/dist/skill/docs/stack/cms/components.md +479 -0
- package/dist/skill/docs/stack/cms/connecting.md +199 -0
- package/dist/skill/docs/stack/cms/dashboard.md +39 -0
- package/dist/skill/docs/stack/cms/index.md +158 -0
- package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
- package/dist/skill/docs/stack/cms/pages.md +275 -0
- package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
- package/dist/skill/docs/stack/cms/schema-format.md +437 -0
- package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
- package/dist/skill/docs/stack/cms/security.md +203 -0
- package/dist/skill/docs/stack/cms/table-views.md +142 -0
- package/dist/skill/docs/stack/index.md +65 -0
- package/dist/skill/docs/stack/queues/handlers.md +317 -0
- package/dist/skill/docs/stack/queues/index.md +56 -0
- package/dist/skill/docs/stack/queues/using-queues.md +192 -0
- package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/dist/skill/docs/stack/realtime/index.md +73 -0
- package/dist/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
- package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/dist/skill/docs/stack/storage/index.md +17 -0
- package/dist/skill/docs/stack/storage/kv.md +204 -0
- package/dist/skill/docs/stack/storage/r2.md +232 -0
- package/dist/skill/docs/stack/storage/using-kv.md +70 -0
- package/dist/skill/docs/stack/storage/using-r2.md +55 -0
- package/dist/skill/docs/stack/vector/embeddings.md +554 -0
- package/dist/skill/docs/stack/vector/index.md +44 -0
- package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
- package/dist/skill/docs/stack/webhooks/index.md +36 -0
- package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +142 -1051
- package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/src/skill/docs/changelog.md +1225 -0
- package/src/skill/docs/compiler/claude-code-skill.md +312 -0
- package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/src/skill/docs/compiler/config/agents.md +144 -0
- package/src/skill/docs/compiler/config/auth.md +109 -0
- package/src/skill/docs/compiler/config/bindings.md +176 -0
- package/src/skill/docs/compiler/config/domains.md +149 -0
- package/src/skill/docs/compiler/config/index.md +419 -0
- package/src/skill/docs/compiler/config/output.md +338 -0
- package/src/skill/docs/compiler/config/providers.md +248 -0
- package/src/skill/docs/compiler/config/security.md +255 -0
- package/src/skill/docs/compiler/config/single-tenant.md +128 -0
- package/src/skill/docs/compiler/config/variables.md +157 -0
- package/src/skill/docs/compiler/definitions/access.md +445 -0
- package/src/skill/docs/compiler/definitions/actions.md +884 -0
- package/src/skill/docs/compiler/definitions/concepts.md +52 -0
- package/src/skill/docs/compiler/definitions/feature.md +164 -0
- package/src/skill/docs/compiler/definitions/firewall.md +285 -0
- package/src/skill/docs/compiler/definitions/guards.md +241 -0
- package/src/skill/docs/compiler/definitions/index.md +219 -0
- package/src/skill/docs/compiler/definitions/masking.md +241 -0
- package/src/skill/docs/compiler/definitions/read.md +220 -0
- package/src/skill/docs/compiler/definitions/schema.md +697 -0
- package/src/skill/docs/compiler/definitions/validation.md +35 -0
- package/src/skill/docs/compiler/definitions/views.md +292 -0
- package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/src/skill/docs/compiler/getting-started/index.md +192 -0
- package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/src/skill/docs/compiler/getting-started/templates.md +111 -0
- package/src/skill/docs/compiler/index.md +85 -0
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/src/skill/docs/compiler/targets/index.md +47 -0
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/src/skill/docs/compiler/troubleshooting.md +120 -0
- package/src/skill/docs/index.md +77 -0
- package/src/skill/docs/stack/account-ui/customization.md +378 -0
- package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/src/skill/docs/stack/account-ui/features/index.md +291 -0
- package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/src/skill/docs/stack/account-ui/hooks.md +209 -0
- package/src/skill/docs/stack/account-ui/index.md +147 -0
- package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/src/skill/docs/stack/account-ui/standalone.md +149 -0
- package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/src/skill/docs/stack/account-ui/worker.md +362 -0
- package/src/skill/docs/stack/auth/api-keys.md +15 -0
- package/src/skill/docs/stack/auth/device-auth.md +14 -0
- package/src/skill/docs/stack/auth/index.md +64 -0
- package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/src/skill/docs/stack/auth/plugins/index.md +340 -0
- package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/src/skill/docs/stack/auth/security.md +455 -0
- package/src/skill/docs/stack/auth/using-auth.md +39 -0
- package/src/skill/docs/stack/cms/actions.md +199 -0
- package/src/skill/docs/stack/cms/components.md +479 -0
- package/src/skill/docs/stack/cms/connecting.md +199 -0
- package/src/skill/docs/stack/cms/dashboard.md +39 -0
- package/src/skill/docs/stack/cms/index.md +158 -0
- package/src/skill/docs/stack/cms/inline-editing.md +136 -0
- package/src/skill/docs/stack/cms/pages.md +275 -0
- package/src/skill/docs/stack/cms/record-layouts.md +151 -0
- package/src/skill/docs/stack/cms/schema-format.md +437 -0
- package/src/skill/docs/stack/cms/schema-registry.md +200 -0
- package/src/skill/docs/stack/cms/security.md +203 -0
- package/src/skill/docs/stack/cms/table-views.md +142 -0
- package/src/skill/docs/stack/index.md +65 -0
- package/src/skill/docs/stack/queues/handlers.md +317 -0
- package/src/skill/docs/stack/queues/index.md +56 -0
- package/src/skill/docs/stack/queues/using-queues.md +192 -0
- package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/src/skill/docs/stack/realtime/index.md +73 -0
- package/src/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
- package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/src/skill/docs/stack/storage/index.md +17 -0
- package/src/skill/docs/stack/storage/kv.md +204 -0
- package/src/skill/docs/stack/storage/r2.md +232 -0
- package/src/skill/docs/stack/storage/using-kv.md +70 -0
- package/src/skill/docs/stack/storage/using-r2.md +55 -0
- package/src/skill/docs/stack/vector/embeddings.md +554 -0
- package/src/skill/docs/stack/vector/index.md +44 -0
- package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/src/skill/docs/stack/webhooks/inbound.md +186 -0
- package/src/skill/docs/stack/webhooks/index.md +36 -0
- package/src/skill/docs/stack/webhooks/outbound.md +281 -0
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# Using Embeddings
|
|
2
|
+
|
|
3
|
+
This page covers the runtime API for working with embeddings — the generated endpoints, the search service, and practical usage patterns.
|
|
4
|
+
|
|
5
|
+
## Embeddings API
|
|
6
|
+
|
|
7
|
+
When any feature has embeddings configured, the compiler generates these endpoints:
|
|
8
|
+
|
|
9
|
+
### Generate Embedding
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
POST /api/v1/embeddings
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Enqueue an embedding job for arbitrary content:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
curl -X POST https://api.example.com/api/v1/embeddings \
|
|
19
|
+
-H "Content-Type: application/json" \
|
|
20
|
+
-H "Cookie: better-auth.session_token=..." \
|
|
21
|
+
-d '{
|
|
22
|
+
"content": "Text to generate an embedding for",
|
|
23
|
+
"model": "@cf/baai/bge-base-en-v1.5",
|
|
24
|
+
"table": "jobs",
|
|
25
|
+
"id": "job_123"
|
|
26
|
+
}'
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
**Request body:**
|
|
30
|
+
|
|
31
|
+
| Field | Type | Required | Description |
|
|
32
|
+
|-------|------|----------|-------------|
|
|
33
|
+
| `content` | string | Yes | Text to embed |
|
|
34
|
+
| `model` | string | No | Embedding model (defaults to table config or `@cf/baai/bge-base-en-v1.5`) |
|
|
35
|
+
| `table` | string | No | Table to store the embedding in |
|
|
36
|
+
| `id` | string | Conditional | Record ID (required when `table` is provided) |
|
|
37
|
+
|
|
38
|
+
**Response:**
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"queued": true,
|
|
43
|
+
"jobId": "550e8400-e29b-41d4-a716-446655440000",
|
|
44
|
+
"table": "jobs",
|
|
45
|
+
"id": "job_123",
|
|
46
|
+
"model": "@cf/baai/bge-base-en-v1.5"
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
This endpoint is useful for:
|
|
51
|
+
- Re-embedding existing records
|
|
52
|
+
- Embedding content that doesn't go through CRUD routes
|
|
53
|
+
- Batch embedding via scripts
|
|
54
|
+
|
|
55
|
+
### List Embedding Tables
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
GET /api/v1/embeddings/tables
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
List tables that have embeddings configured:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"tables": [
|
|
66
|
+
{
|
|
67
|
+
"name": "jobs",
|
|
68
|
+
"embeddingColumn": "embedding",
|
|
69
|
+
"model": "@cf/baai/bge-base-en-v1.5"
|
|
70
|
+
}
|
|
71
|
+
]
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Search Service
|
|
76
|
+
|
|
77
|
+
For typed similarity search with classification, use the `createEmbeddings()` service generated from `defineEmbedding()` configurations.
|
|
78
|
+
|
|
79
|
+
### Basic Search
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
const embeddings = createEmbeddings(ctx.env);
|
|
83
|
+
|
|
84
|
+
const results = await embeddings.jobSimilarity.search(
|
|
85
|
+
"Senior backend engineer with distributed systems experience",
|
|
86
|
+
{
|
|
87
|
+
department: "Engineering",
|
|
88
|
+
limit: 5,
|
|
89
|
+
threshold: 0.70,
|
|
90
|
+
}
|
|
91
|
+
);
|
|
92
|
+
|
|
93
|
+
// Returns: [{ id, score, classification, metadata }]
|
|
94
|
+
for (const match of results) {
|
|
95
|
+
console.log(`${match.classification}: ${match.id} (score: ${match.score})`);
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Classification
|
|
100
|
+
|
|
101
|
+
Results are automatically classified based on similarity score:
|
|
102
|
+
|
|
103
|
+
| Classification | Default Threshold | Meaning |
|
|
104
|
+
|----------------|-------------------|---------|
|
|
105
|
+
| `DUPLICATE` | >= 0.90 | Near-identical job posting |
|
|
106
|
+
| `SIMILAR_ROLE` | >= 0.85 | Strongly similar role requirements |
|
|
107
|
+
| `RELATED` | >= 0.75 | Topically related position |
|
|
108
|
+
| `NEW` | < 0.75 | No significant match |
|
|
109
|
+
|
|
110
|
+
### Gray Zone Detection
|
|
111
|
+
|
|
112
|
+
For cases where automatic classification isn't sufficient, use gray zone detection:
|
|
113
|
+
|
|
114
|
+
```typescript
|
|
115
|
+
const results = await embeddings.jobSimilarity.findWithGrayZone(
|
|
116
|
+
"Full-stack developer with React and Node.js",
|
|
117
|
+
{ min: 0.60, max: 0.85 }
|
|
118
|
+
);
|
|
119
|
+
|
|
120
|
+
// results.high_confidence — Score >= 0.85 (auto-classified)
|
|
121
|
+
// results.gray_zone — 0.60 <= score < 0.85 (needs review)
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Raw Embedding
|
|
125
|
+
|
|
126
|
+
Generate an embedding vector without searching:
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
const vector = await embeddings.jobSimilarity.embed("Text to embed");
|
|
130
|
+
// Returns: number[] (768 dimensions for bge-base)
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Vectorize Queries
|
|
134
|
+
|
|
135
|
+
If your project uses a Vectorize index, you can query it directly for custom search logic:
|
|
136
|
+
|
|
137
|
+
```typescript
|
|
138
|
+
// Generate embedding for query text
|
|
139
|
+
const queryVector = await embeddings.jobSimilarity.embed(searchText);
|
|
140
|
+
|
|
141
|
+
// Query Vectorize with metadata filters
|
|
142
|
+
const results = await ctx.env.VECTORIZE.query(queryVector, {
|
|
143
|
+
topK: 10,
|
|
144
|
+
filter: {
|
|
145
|
+
department: "Engineering",
|
|
146
|
+
organizationId: ctx.activeOrgId,
|
|
147
|
+
},
|
|
148
|
+
});
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
The `metadata` fields in your `defineTable` embeddings config are automatically included in the Vectorize index, enabling filtered searches.
|
|
152
|
+
|
|
153
|
+
## Auto-Embed vs Manual
|
|
154
|
+
|
|
155
|
+
| Trigger | How | Use Case |
|
|
156
|
+
|---------|-----|----------|
|
|
157
|
+
| Auto (INSERT) | Compiler enqueues after successful create | Default behavior |
|
|
158
|
+
| Auto (UPDATE) | Compiler enqueues when watched fields change | Keeps embeddings fresh |
|
|
159
|
+
| Manual (API) | `POST /api/v1/embeddings` | Re-embedding, batch jobs |
|
|
160
|
+
| Manual (Queue) | `env.EMBEDDINGS_QUEUE.send(...)` | Custom pipelines |
|
|
161
|
+
|
|
162
|
+
## Security
|
|
163
|
+
|
|
164
|
+
- The embeddings API requires authentication
|
|
165
|
+
- Jobs are scoped to the user's `activeOrgId`
|
|
166
|
+
- Embedding jobs are only enqueued after all security checks pass (auth, firewall, guards)
|
|
167
|
+
- The queue consumer is an internal process — it trusts pre-validated jobs
|
|
168
|
+
|
|
169
|
+
## Supported Models
|
|
170
|
+
|
|
171
|
+
| Model | Dimensions | Notes |
|
|
172
|
+
|-------|------------|-------|
|
|
173
|
+
| `@cf/baai/bge-base-en-v1.5` | 768 | Default, good general-purpose |
|
|
174
|
+
| `@cf/baai/bge-small-en-v1.5` | 384 | Faster, smaller |
|
|
175
|
+
| `@cf/baai/bge-large-en-v1.5` | 1024 | Higher quality |
|
|
176
|
+
|
|
177
|
+
See [Workers AI Models](https://developers.cloudflare.com/workers-ai/models/) for the full list.
|
|
178
|
+
|
|
179
|
+
## Cloudflare Only
|
|
180
|
+
|
|
181
|
+
Embeddings require Cloudflare Workers AI and Queues. They are not available with the Bun or Node runtimes.
|
|
182
|
+
|
|
183
|
+
## See Also
|
|
184
|
+
|
|
185
|
+
- [Automatic Embeddings](/stack/vector/embeddings) — `defineTable()` config, `defineEmbedding()` search service, and Vectorize integration
|
|
186
|
+
- [Queues](/stack/queues) — How embedding jobs are processed
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# Inbound Webhooks
|
|
2
|
+
|
|
3
|
+
Inbound webhooks allow external services (Stripe, Paddle, GitHub, etc.) to notify your API of events. Quickback generates endpoints that verify signatures, deduplicate events, and dispatch to your handler functions via a Cloudflare Queue.
|
|
4
|
+
|
|
5
|
+
## Endpoint
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
POST /webhooks/v1/inbound/:provider
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
The `:provider` parameter identifies which service sent the webhook (e.g., `stripe`, `paddle`, `github`). Each provider has its own signature verification logic.
|
|
12
|
+
|
|
13
|
+
## How It Works
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
External Service → POST /webhooks/v1/inbound/stripe
|
|
17
|
+
│
|
|
18
|
+
├─ 1. Verify signature (HMAC-SHA256)
|
|
19
|
+
├─ 2. Parse event (provider-specific)
|
|
20
|
+
├─ 3. Deduplicate via externalId
|
|
21
|
+
├─ 4. Store in webhook_events table
|
|
22
|
+
├─ 5. Enqueue for async processing
|
|
23
|
+
└─ 6. Return 200 OK immediately
|
|
24
|
+
|
|
25
|
+
Queue Consumer
|
|
26
|
+
│
|
|
27
|
+
├─ 1. Update status → 'processing'
|
|
28
|
+
├─ 2. Call registered handlers
|
|
29
|
+
└─ 3. Update status → 'processed' or 'failed'
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The API returns `200 OK` immediately after enqueuing. Your handler logic runs asynchronously via the queue consumer, so external services don't time out waiting for your processing to complete.
|
|
33
|
+
|
|
34
|
+
## Registering Handlers
|
|
35
|
+
|
|
36
|
+
Use `onWebhookEvent()` in your action code to register handlers for specific events:
|
|
37
|
+
|
|
38
|
+
```typescript
|
|
39
|
+
onWebhookEvent("stripe:checkout.session.completed", async (ctx) => {
|
|
40
|
+
const { type, data, provider, env } = ctx;
|
|
41
|
+
await createSubscription(data, env);
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
// Wildcard — handle all events from a provider
|
|
45
|
+
onWebhookEvent("stripe:*", async (ctx) => {
|
|
46
|
+
console.log(`Received ${ctx.type} from ${ctx.provider}`);
|
|
47
|
+
});
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
**Handler context:**
|
|
51
|
+
|
|
52
|
+
| Field | Type | Description |
|
|
53
|
+
|-------|------|-------------|
|
|
54
|
+
| `type` | `string` | Full event type (e.g., `stripe:checkout.session.completed`) |
|
|
55
|
+
| `data` | `unknown` | Parsed event payload |
|
|
56
|
+
| `provider` | `string` | Provider name (e.g., `stripe`) |
|
|
57
|
+
| `env` | `CloudflareBindings` | Cloudflare environment bindings |
|
|
58
|
+
|
|
59
|
+
**Execution order:**
|
|
60
|
+
1. Specific handlers run first (exact match on event type)
|
|
61
|
+
2. Wildcard handlers run after
|
|
62
|
+
3. All matching handlers run in parallel
|
|
63
|
+
4. If any handler throws, the message is retried
|
|
64
|
+
|
|
65
|
+
## Signature Verification
|
|
66
|
+
|
|
67
|
+
Each provider verifies signatures differently. The secret is read from an environment variable.
|
|
68
|
+
|
|
69
|
+
### Stripe
|
|
70
|
+
|
|
71
|
+
**Environment variable:** `STRIPE_WEBHOOK_SECRET`
|
|
72
|
+
|
|
73
|
+
Stripe uses HMAC-SHA256 with a timestamp-based signature:
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
Stripe-Signature: t=1614556800,v1=abc123...
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The signed payload is `<timestamp>.<raw_body>`. Verification checks:
|
|
80
|
+
- HMAC matches
|
|
81
|
+
- Timestamp is within 5 minutes (prevents replay attacks)
|
|
82
|
+
|
|
83
|
+
### Custom Providers
|
|
84
|
+
|
|
85
|
+
Providers implement this interface:
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
interface InboundProvider {
|
|
89
|
+
name: string;
|
|
90
|
+
verifySignature(payload: string, signature: string, secret: string): Promise<boolean>;
|
|
91
|
+
parseEvent(payload: string): {
|
|
92
|
+
type: string;
|
|
93
|
+
data: unknown;
|
|
94
|
+
externalId?: string;
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Idempotency
|
|
100
|
+
|
|
101
|
+
Events are deduplicated on the tuple `(provider, externalId)` (e.g., Stripe's `event.id`). The `webhook_events` table carries a **unique index** on this pair, and inbound delivery uses `INSERT … ON CONFLICT DO NOTHING` so concurrent deliveries collapse deterministically:
|
|
102
|
+
|
|
103
|
+
- The first delivery to win the race inserts the row, enqueues processing, and returns `{ received: true, eventId }`.
|
|
104
|
+
- Any concurrent delivery with the same `(provider, externalId)` short-circuits and returns `{ received: true, duplicate: true }` — the queue is **never** sent the duplicate, so handlers run exactly once.
|
|
105
|
+
|
|
106
|
+
Events without an `externalId` (NULL) are not deduplicated. SQLite treats NULLs as distinct in unique indexes, so providers that don't supply a stable event ID continue to insert one row per delivery.
|
|
107
|
+
|
|
108
|
+
### Migrating an existing deployment
|
|
109
|
+
|
|
110
|
+
The unique index was added in v0.10.x. Existing deployments may have duplicate rows from before the constraint existed; drizzle-kit's migration will fail until they are cleaned up. Run this once before applying the migration:
|
|
111
|
+
|
|
112
|
+
```sql
|
|
113
|
+
DELETE FROM webhook_events
|
|
114
|
+
WHERE rowid NOT IN (
|
|
115
|
+
SELECT MIN(rowid) FROM webhook_events
|
|
116
|
+
WHERE external_id IS NOT NULL
|
|
117
|
+
GROUP BY provider, external_id
|
|
118
|
+
);
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
This keeps the earliest row for each `(provider, external_id)` pair and discards the duplicates.
|
|
122
|
+
|
|
123
|
+
## Database Schema
|
|
124
|
+
|
|
125
|
+
Inbound events are stored in the `webhook_events` table:
|
|
126
|
+
|
|
127
|
+
| Column | Type | Description |
|
|
128
|
+
|--------|------|-------------|
|
|
129
|
+
| `id` | text | Primary key (`whe_<uuid>`) |
|
|
130
|
+
| `provider` | text | Provider name |
|
|
131
|
+
| `eventType` | text | Event type from provider |
|
|
132
|
+
| `externalId` | text | Provider's event ID (for deduplication) |
|
|
133
|
+
| `payload` | text | Raw JSON payload |
|
|
134
|
+
| `status` | text | `received`, `processing`, `processed`, `failed` |
|
|
135
|
+
| `attempts` | integer | Processing attempt count |
|
|
136
|
+
| `processedAt` | timestamp | When successfully processed |
|
|
137
|
+
| `error` | text | Error message if failed |
|
|
138
|
+
| `createdAt` | timestamp | When received |
|
|
139
|
+
|
|
140
|
+
## Admin Routes
|
|
141
|
+
|
|
142
|
+
Two admin-only routes are generated for monitoring inbound webhooks:
|
|
143
|
+
|
|
144
|
+
### List Events
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
GET /webhooks/v1/inbound/events
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Returns recent inbound events with their status. Requires admin role.
|
|
151
|
+
|
|
152
|
+
### Retry Failed Event
|
|
153
|
+
|
|
154
|
+
```
|
|
155
|
+
POST /webhooks/v1/inbound/events/:id/retry
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Re-queues a failed event for processing. Requires admin role.
|
|
159
|
+
|
|
160
|
+
## Error Handling
|
|
161
|
+
|
|
162
|
+
- **Invalid signature** — Returns `401 Unauthorized`, event not stored
|
|
163
|
+
- **Handler failure** — Event marked as `failed`, message retried (up to 3 times via queue)
|
|
164
|
+
- **All retries exhausted** — Event remains in `failed` status; use the admin retry endpoint to re-process manually
|
|
165
|
+
|
|
166
|
+
## Configuration
|
|
167
|
+
|
|
168
|
+
Webhooks are enabled by setting `webhooksBinding` in your database config:
|
|
169
|
+
|
|
170
|
+
```typescript
|
|
171
|
+
database: defineDatabase("cloudflare-d1", {
|
|
172
|
+
binding: "DB",
|
|
173
|
+
webhooksBinding: "WEBHOOKS_DB",
|
|
174
|
+
})
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Set the provider secret as a Wrangler secret:
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
wrangler secret put STRIPE_WEBHOOK_SECRET
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## See Also
|
|
184
|
+
|
|
185
|
+
- [Outbound Webhooks](/stack/webhooks/outbound) — Send webhooks when data changes
|
|
186
|
+
- [Queues](/stack/queues) — Background processing infrastructure
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Webhooks
|
|
2
|
+
|
|
3
|
+
Quickback supports both inbound and outbound webhooks for integrating with external services. Inbound webhooks receive events from providers like Stripe, while outbound webhooks notify your users' integrations when data changes.
|
|
4
|
+
|
|
5
|
+
## Enabling Webhooks
|
|
6
|
+
|
|
7
|
+
Set `webhooksBinding` in your database provider config:
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
database: defineDatabase("cloudflare-d1", {
|
|
11
|
+
binding: "DB",
|
|
12
|
+
webhooksBinding: "WEBHOOKS_DB",
|
|
13
|
+
})
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
This generates:
|
|
17
|
+
- Webhook database schema (3 tables: events, endpoints, deliveries)
|
|
18
|
+
- Inbound endpoint at `POST /webhooks/v1/inbound/:provider`
|
|
19
|
+
- Outbound endpoint management API at `/webhooks/v1/endpoints`
|
|
20
|
+
- Queue consumer for async delivery with retry
|
|
21
|
+
- HMAC-SHA256 payload signing (Stripe-compatible format)
|
|
22
|
+
|
|
23
|
+
## Infrastructure
|
|
24
|
+
|
|
25
|
+
Webhooks use a Cloudflare Queue for reliable async processing:
|
|
26
|
+
|
|
27
|
+
| Component | Binding | Purpose |
|
|
28
|
+
|-----------|---------|---------|
|
|
29
|
+
| Queue | `WEBHOOKS_QUEUE` | Process inbound events and deliver outbound webhooks |
|
|
30
|
+
| Dead letter queue | `WEBHOOKS_DLQ` | Capture failed deliveries after max retries |
|
|
31
|
+
| Database | `WEBHOOKS_DB` | Store events, endpoints, and delivery records |
|
|
32
|
+
|
|
33
|
+
## Pages
|
|
34
|
+
|
|
35
|
+
- [Inbound Webhooks](/stack/webhooks/inbound) — Receive webhooks from Stripe, Paddle, GitHub, etc.
|
|
36
|
+
- [Outbound Webhooks](/stack/webhooks/outbound) — Send signed webhooks when data changes
|
|
@@ -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.
|
|
3
|
+
"version": "0.11.0",
|
|
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",
|