Event Automations

Run an automation each time a webhook arrives, through a Doorstep event relay.

An event automation runs each time a webhook arrives at an event source, instead of at a set time. Use one to triage new GitHub issues, react to a payment, or handle a form submission.

Webhooks reach Crumble through an event relay: a Doorstep server that receives webhooks for your account and holds them. Crumble opens its own connection to the relay, so your server needs no public address. Events that arrive while your server is offline wait on the relay for up to seven days.

Set up the event relay

1. Run a Doorstep relay, or use one someone runs for you. Doorstep’s README covers the single binary and Cloudflare Workers.
2. Create a Doorstep account with the relay’s admin token, and keep the account token it returns.
3. In Crumble, open Settings > Event relay.
4. Next to Doorstep account token, select Add. Paste the token, or select a connected password manager and paste a reference to it.
5. In Relay URL, enter the relay’s address, such as https://relay.example.com, and select Save.

The Relay URL row shows Connected once the relay accepts the token. If the connection drops, Crumble reconnects automatically with a growing delay.

Add an event source

An event source is one webhook address on the relay. Every bot of the account can use it.

1. In Settings > Event relay, select Add source.
2. Enter a name, such as GitHub issues, and select Add.
3. Copy the webhook address and paste it into the provider’s webhook settings.

Crumble shows the address only once. Anyone who has it can send events to the source, so keep it private. To revoke an address, delete the source; you can delete a source only while no automation uses it.

Create an event automation

On the Automations page, select New automation. Under When, select Event and pick a source. You can also ask a bot, such as “When an issue arrives from GitHub issues, label and summarize it.”

Every event from the source starts every enabled automation that uses it. Choose which events the provider sends in its own webhook settings, and use a separate source for each purpose. One automation handles its events one at a time, oldest first.

What the bot receives

A prompt automation sends its prompt to the bot’s chat, followed by the event: the method, query string, headers, and body. The chat shows only the prompt, labeled with the automation and the source.

The event is marked as untrusted data from outside Crumble. Text in a webhook can come from anyone, such as the author of a GitHub issue, so the bot must not follow instructions in it. Intent checks count only the automation’s prompt as your request, never the event.

Bodies longer than 32 KiB are cut, and bodies that aren’t UTF-8 text are left out. In both cases the bot reads the rest with its event_payload tool, a page at a time.

A script automation gets the event in a file instead. These environment variables are set for its command:

Limits