Lure#

Lure is a library for processing webhook events into LLM-consumable prompts. It looks something like this:

1. An HTTP request is received at a path like /webhooks/tangled
2. Lure matches the path to a template file on disk, e.g. ./lures/tangled.lure. The .lure file is part config, part template (more on this later).
3. According to the config, Lure validates the webhook according to the specified strategy (e.g. API key or HMAC verification)
4. If validation succeeds, Lure executes some callback with the string result of evaluating the template contents with the webhook payload.

The goal is to trigger LLM executions in response to webhook events, but without the requirement for Zapier/IFTTT and with as little HTTP endpoint exposure as possible. Consumers of the Lure library provide their own HTTP server--no server is provided by Lure.

.lure file format#

Lures are intended to be written by LLMs, so a .lure file is essentially a Markdown file with frontmatter. Here is a contrived example:

---
register: manual
verify:
  hmac:
    location: header
    name: X-My-Header-Signature
    secret: $MY_WEBHOOK_SECRET
payload:
  contentType: json
  schema: https://example.com/schema
config:
  arbitrary: true
  someValue: 3
---

You have received information about a <%= it.payload.event => event on My
Service. Read the following payload and respond according to your skills:

<%= it.payload.body %>

Different registration and verification methods can be supported, for generic implementations or vendor-specific requirements. Only one verification method can be specified per lure.

Usage#

Use either the @lure/fetch or @lure/express packages to construct an endpoint handler that suits your HTTP server of choice.

Both handler constructors take the following parameters:

• configSchema: A Standard Schema for validating any extra config you would like to allow in the config frontmatter key
• luresDir: A path to a directory of lures
• callback: A function that you want to run in response to incoming webhooks. It will be called with the templated prompt prompt and the value of the config frontmatter value.

Lifecycle#

At Startup#

1. The parent program creates either a fetch or an Express lure handler, as described above.
2. Lure traverses the specified directory and discovers any .lure files.
3. Each .lure file has their frontmatter validated. The parsed config and template content are cached.

Per Request#

1. The requested path is checked against registered lure paths.
2. On a hit, we immediately return a 204 response, to keep the response time as low as possible.
3. Webhook requests are copied and added to a queue for processing.
4. The queue processor removes requests from the queue FIFO. If verification fails, the request is dropped.
5. On successful verification, the lure template is evaluated using the request.
6. Finally, the provided callback is executed with the fully-formed prompt, and the config object from the original .lure frontmatter.