Create a trigger
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
Withmode: "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:
truematches,falseends the rule’s outcome asfiltered. - 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 macrosexists,all,map, andfilter, 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
failedwithfilter_error; it is never retried.
400 with the field, such as rules[review].filter, and CEL’s message with its position.
Templates
A rule’smessage and its session key are templates: plain text with {{path}} placeholders that place values from the same three variables.
Verify signatures
Withverification, 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 thededupe 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.
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.
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 inkey 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.