Enable LLMs to handle webhooks with plaintext files
update README with design clarifications
+33
-14
+31
-14
README.md
+31
-14
README.md
···
4
4
looks something like this:
5
5
6
6
1. An HTTP request is received at a path like `/webhooks/tangled`
7
-
2. Lure matches the path to a template file on disk, e.g.
8
-
`./lures/tangled.lure`. The `.lure` file is part config, part template (more
9
-
on this later).
7
+
2. Lure strips the configured base path and matches the remainder to a template
8
+
file on disk, e.g. with base path `/webhooks`, the path `/webhooks/tangled`
9
+
matches `./lures/tangled.lure`. Nested paths are supported: `/webhooks/github/push`
10
+
matches `./lures/github/push.lure`. The `.lure` file is part config, part
11
+
template (more on this later).
10
12
3. According to the config, Lure validates the webhook according to the
11
13
specified strategy (e.g. API key or HMAC verification)
12
14
4. If validation succeeds, Lure executes some callback with the string result of
···
24
26
25
27
```md
26
28
---
27
-
register: manual
28
29
verify:
29
30
hmac:
30
31
location: header
···
32
33
secret: $MY_WEBHOOK_SECRET
33
34
payload:
34
35
contentType: json
35
-
schema: https://example.com/schema
36
36
config:
37
37
arbitrary: true
38
38
someValue: 3
39
39
---
40
40
41
-
You have received information about a <%= it.payload.event => event on My
41
+
You have received information about a <%= it.payload.event %> event on My
42
42
Service. Read the following payload and respond according to your skills:
43
43
44
44
<%= it.payload.body %>
45
45
```
46
46
47
-
Different registration and verification methods can be supported, for generic
48
-
implementations or vendor-specific requirements. Only one verification method
49
-
can be specified per lure.
47
+
Different verification methods can be supported, for generic implementations or
48
+
vendor-specific requirements. Only one verification method can be specified per
49
+
lure.
50
+
51
+
### Template scope
52
+
53
+
Templates are evaluated using [eta](https://eta.js.org). The following
54
+
properties are available on `it`:
55
+
56
+
- `it.payload`: The request body. For `contentType: json`, this is the parsed
57
+
JSON value.
58
+
- `it.headers`: The request headers as a [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) object.
59
+
- `it.query`: The query string parameters as a [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object.
50
60
51
61
## Usage
52
62
···
55
65
56
66
Both handler constructors take the following parameters:
57
67
68
+
- `basePath`: The URL path prefix under which all lure endpoints are mounted,
69
+
e.g. `/webhooks`. Lure only handles requests whose path begins with this
70
+
prefix; all other requests are passed through.
58
71
- `configSchema`: A Standard Schema for validating any extra config you would
59
72
like to allow in the `config` frontmatter key
60
73
- `luresDir`: A path to a directory of lures
61
74
- `callback`: A function that you want to run in response to incoming webhooks.
62
75
It will be called with the templated prompt `prompt` and the value of the
63
76
`config` frontmatter value.
77
+
- `maxAttempts`: How many times to attempt the `callback` before giving up.
78
+
Defaults to `1` (no retries). If all attempts fail, the webhook is dropped.
64
79
65
80
## Lifecycle
66
81
···
77
92
1. The requested path is checked against registered lure paths.
78
93
2. On a hit, we immediately return a 204 response, to keep the response
79
94
time as low as possible.
80
-
3. Webhook requests are copied and added to a queue for processing.
81
-
3. The queue processor removes requests from the queue FIFO. If verification
95
+
3. Webhook requests are copied and added to an in-memory queue for processing.
96
+
Requests in the queue will be lost if the process exits.
97
+
4. The queue processor removes requests from the queue FIFO. If verification
82
98
fails, the request is dropped.
83
-
4. On successful verification, the lure template is evaluated using the
99
+
5. On successful verification, the lure template is evaluated using the
84
100
request.
85
-
5. Finally, the provided `callback` is executed with the fully-formed prompt,
86
-
and the config object from the original `.lure` frontmatter.
101
+
6. The provided `callback` is executed with the fully-formed prompt and the
102
+
config object from the original `.lure` frontmatter. If the callback throws,
103
+
it will be retried up to `maxAttempts` times before the webhook is dropped.