Skip to main content
A trigger is a webhook endpoint of your project. Any service can post JSON events to its URL, and its rules decide which events become which messages, in which agent’s session. An event-driven agent needs no server of yours in between: paddock receives the event, records it, finds or creates the session, and sends the message.

Create a trigger

Give the sender trigger.url and, if the trigger verifies signatures, the same secret. The Python SDK takes requests as dictionaries spelled as the API spells them (agentId), or as the models in paddock.types. The trigger’s ID, trg_..., is the last segment of its URL. The URL is unguessable; a trigger without verification accepts every request to it.

Rules

Each rule picks the events it wants and sends each as a message to a session of one agent. Every enabled rule that matches an event fires, independently of the others: each has its own outcome, session, and message, and their order only decides the order they run in.

Sessions by key

With mode: "key", the rule renders its key template from the event, then reuses the agent’s session whose triggerKey metadata equals that key, or creates one with the rule’s session settings and that key. So every event about one pull request lands in one conversation, and the agent answers with its earlier work in context. Two rules that render the same key for the same agent reach the same session, each with its own message. With mode: "new", every event gets a new session. Find a rule’s sessions with a metadata filter:

Filters

A filter is a CEL expression over three variables, built from the request as the sender sent it:
  • The expression must yield a boolean: true matches, false ends the rule’s outcome as filtered.
  • Reading a key that is not there is an error. Test first with has(body.x) or "x-github-event" in headers. && and || absorb an error when the other side decides the result, so a check that fails first protects the checks after it.
  • Available: comparisons, in, has(), size(), contains, startsWith, endsWith, matches, the macros exists, all, map, and filter, and cel-go’s string extensions (lowerAscii, upperAscii, trim, split, join, replace, substring, indexOf, format, and more) and list extensions (slice, flatten, distinct, sort, hasAny, hasAll, and more).
  • At most 4 KiB. Every evaluation is bounded in cost and time.
  • An evaluation that fails ends the rule’s outcome as failed with filter_error; it is never retried.
Every filter and the dedupe expression are compiled when you create or update the trigger; a mistake is 400 with the field, such as rules[review].filter, and CEL’s message with its position.

Templates

A rule’s message and its session key are templates: plain text with {{path}} placeholders that place values from the same three variables.

Verify signatures

With verification, paddock computes the HMAC-SHA256 of the raw body with the trigger’s secret, writes it as lowercase hexadecimal after prefix, and compares it with the header’s value. The header name is matched in any case. A missing or wrong signature is answered 401 and recorded as a rejected delivery. The secret is returned only by its own operations. Rotating it replaces it at once: requests signed with the old secret fail from then on, so give the sender the new one.

Deduplication

Senders redeliver events after a timeout. Every accepted request gets a dedupe key: the SHA-256 of the dedupe expression’s value, such as GitHub’s X-GitHub-Delivery header, or of the raw body when the trigger has none, or the expression fails or yields anything but a non-empty string. A request whose key matches a delivery the trigger already has is answered 200 { deliveryId, duplicate: true } and does nothing. Deliveries are kept until the trigger is deleted, so a duplicate is recognized however late it comes.

Test rules on a sample event

triggers.test runs a draft trigger’s rules on a sample event exactly as a real request would, after the signature: the dedupe expression, then each enabled rule’s filter and both templates. It stores nothing and sends nothing, and the trigger need not exist.
Each rule’s result says whether it is enabled, whether it matched, its first error with the code a real outcome would record, the rendered session key and message, and missing, the message paths that led nowhere. The console’s rule editor runs this on every edit; see Console.

Deliveries

Every request to an existing trigger is a delivery. paddock records it durably and answers before doing anything else, then delivers it in the background. A sender waits only for the record, so a slow agent wake never times it out. Each delivery has one outcome per rule that was enabled when it arrived:
deliveries.get(id) adds the request as the sender sent it: its headers, query, and body. Deliveries are listed newest first and kept, with their requests, until the trigger is deleted.

What a delivery promises

  • Exactly one message per rule. A rule’s message is appended in the same transaction that marks its outcome delivered, so a delivery retried after a crash never sends a message twice.
  • Fixed on receipt. Filters and templates run when the request arrives, so editing or disabling a rule later never changes what a recorded delivery sends.
  • In order per session key. Deliveries for one agent and one session key are delivered in the order they arrived; a later one waits until the earlier ones are final. Other keys are not held back.
  • Bounded retries. A failure that may pass, such as a service briefly unavailable, is retried up to 5 attempts in total, 30 seconds, 2 minutes, 8 minutes, and 32 minutes apart; then the outcome fails with its last error. A failure that would repeat, such as agent_not_found, fails at once. A delivery stuck in retries holds back later deliveries for its key for at most about 43 minutes.
Once a message is delivered it is the session’s like any message you send, and a turn that fails is retried by the agent.

Replay

Replay delivers a recorded request again, for real, as a new delivery that runs the rules as they are now. Deduplication never drops it, and the signature is not checked again. A rule in key mode reaches the same session the first delivery reached, if it still exists. A rejected delivery cannot be replayed (409 conflict).

Update and delete

triggers.update(id, spec) replaces the name, the verification, the dedupe expression, and the whole list of rules, so send the whole trigger every time, without its secret; a field you leave out is cleared. The ID, the URL, and the secret stay. Deleting a trigger makes its URL answer 404 at once and removes its deliveries; the sessions its rules created stay.
The webhook endpoint’s answers are on Trigger webhook. For a complete setup, see the pull request reviewer.