Webhooks and events

Start a bot's work when any service sends an event, through a small gateway you run.

An event subscription starts a bot's work when a service sends something: a pull request changes, a payment comes in, a script finishes. Each event runs the subscription's task in the bot's direct chat on its Runner.

A gateway you run receives the service's request on your own HTTPS address, checks it, and hands it to Lorca, which encrypts it for the bot's Runner, so the request never leaves your computers unencrypted. To follow a pull request, or to give a routine a URL any service can call, you need none of this: Lorca hosts both, see pull request watches and webhooks.

Set up GitHub pull request events

Subscriptions are made with the command line on the bot's Runner. lorca status lists your bots with their ids.

Describe the subscription

pr-events.json

{
  "name": "PR changes",
  "source": "gateway_hmac",
  "bot_id": "bot-12345678",
  "prompt": "Summarize new PR activity. Read the PR to check its current state, and tell me what needs attention.",
  "event_types": ["github.pull_request"],
  "filters": [
    { "pointer": "/repository/full_name", "equals": "acme/project" },
    { "pointer": "/action", "equals": "synchronize" }
  ],
  "queue_policy": "fifo",
  "is_enabled": true
}

prompt is the bot's task for each event. An event runs only when its type is listed and every filter matches: pointer is a path into the event's JSON. With queue_policy fifo events run one at a time in order; latest keeps only the newest event that is waiting.

lorca events add pr-events.json
lorca events route <id> ~/private/pr-route.json

route writes the gateway's key and where to send events to a private file.

Run the gateway

The gateway is scripts/event-gateway.py. Run it on the Runner or on another of your computers where lorca serve runs, with the route and a random GitHub webhook secret of at least 32 characters in a file:

python3 event-gateway.py --route ~/private/pr-route.json \
  --github-secret-file ~/private/github-secret --lorca "$(command -v lorca)"

It listens on 127.0.0.1:8984/github. Put your HTTPS reverse proxy or tunnel in front of it.

Add the webhook on GitHub

In the repository's webhook settings, set your public URL, JSON content, the same secret, and Pull requests events.

What a bot does with an event

The chat shows Event · PR changes, and the bot does the task. What the service sent is information for the bot, never an instruction. Nobody is there to answer a question, so an action that would ask you waits for your review instead. The work counts toward the chat's limits, or the routine's.

If you haven't written in any chat for seven days, events wait and run once you're back. Each event runs at most once, even when the service sends it again.

Manage subscriptions

Command	What it does
`lorca events list`	Each subscription, its state, what waits, its latest deliveries, and why anything is held. Never a key or an event's content.
`lorca events edit <id> <file>`	Replaces the configuration. The bot and routine stay.
`lorca events pause <id>`, `resume <id>`	Holds the work while events keep arriving, and runs it again.
`lorca events reconnect <id>`	Makes a new key; export a new route afterwards.
`lorca events retry <delivery>`, `discard <delivery>`	Runs a failed event again after you've read the chat, or drops it.
`lorca events remove <id>`	Deletes the subscription.

When an event's work fails or is cut off, later events wait until you retry or discard it, and Attention lists "Events on hold". A gateway whose key no longer works shows as "Events refused".