payloadSchema, declared when the trigger is created (integration triggers declare theirs per provider event). Every fire of POST /v1/automations/triggers/{triggerEventId}/fire is validated against it. You can also store a richer contract per trigger, versioned and renderable as types, which the /contract endpoints below cover. This guide turns those contracts into TypeScript types in your codebase, keeps them from drifting, and shows where Brew checks real fires against them.
Nested payload values (objects and arrays) are accepted everywhere. Address a nested leaf by its dotted path, such as
{{ trigger.user.plan }}. See Nested Payloads.Generate Types with brew-cli
brew-cli types writes one file with a type per trigger contract (the command needs a key with the automations scope):
/contract?format=ts artifact, matching in-app Copy as TypeScript and the SKILL.md brief. Stored contracts keep their minted type name when a trigger is renamed. A derived contract uses PascalCase of the current trigger title plus Payload.
Colliding names get the trigger id appended so the file always compiles. A failed contract read leaves the existing output file untouched.
The generated types describe accepted inputs. A field is optional when required: false or a fallback satisfies its presence requirement. Those fields also accept null or an empty string, which Brew treats as missing.
The API resolves fallbacks; generated validators do not insert them. A required field without a fallback must be present. The email field identifies the recipient downstream automations route on.
In CI, gate drift with:
1 when the brand’s contracts no longer match the committed file, which is the signal to regenerate and review the diff. A trigger schema edit shows up as a type change in code review instead of a runtime surprise.
Store a Contract
Brew derives a contract on every read, so the guide above works with no setup. You can also store one per trigger. A stored contract is content-hash versioned and served fromGET /v1/automations/triggers/{triggerEventId}/contract.
The response says which kind you got. source: "stored" carries a
contractHash, a version, and an enforcement mode.
With no stored contract, source is derived instead. derived_from_schema is
built from the trigger’s flat payloadSchema, and the enum also allows
derived_from_template. A derived contract can carry
type: "unknown" where there was no type evidence to work from.
Fields form a tree. Scalars are string, int, float, boolean, date, or
enum. An object node carries children. An array node carries either
children for an element object shape, or itemType for scalar elements.
Pass ?format= to get a generated artifact instead of the JSON contract:
format. The default, json, returns { format, fields } and no content. ts, zod, jsonschema, and skill each return { format, content } and no fields.
Branch on format before reading either key. POST /v1/payload-contracts/infer is different: it returns { fields, issues }, with no format or content.
date fields accept date-only strings such as 2026-10-12 and timestamps such as 2026-10-12T16:00:00.000-04:00 or 2026-10-12T20:00:00.000Z. Values keep their supplied representation.
The compatibility rule requires a YYYY-MM-DD prefix and a successful JavaScript Date.parse check. This preserves the existing local and space-separated datetime forms. Date examples and fallbacks must pass that same check before a contract can be saved.
Generated Zod schemas apply this rule directly. They reject undeclared keys in strict mode and strip them in prune mode, including inside nested objects and arrays. They validate contract inputs; authentication, recipient eligibility, and fire resource limits remain server checks.
JSON Schema exports use the custom brew-date format plus a shared prefix pattern. Register the parseability check in your validator for complete date validation. Standard date-time alone would exclude date-only and legacy accepted forms.
Given a fetched contract response named contract, register the format with AJV 2020:
pattern checks the prefix separately. JSON Schema defaults describe Brew’s fallback behavior; they are not instructions to mutate the integration’s payload.
Declare or replace the stored contract with PUT on the same URL:
- The whole tree validates before anything is written. Unknown-typed nodes
are refused, so declare a concrete type. Keys must be unique per level, and
an
objectfield must declare at least one child. - Two top-level fields can’t land on one contact field. A fire copies
top-level scalar fields onto the contact under their
folded camelCase name, so
planandPlan, orteam_sizeandTeam Size, would write one field twice. APUTdeclaring such a pair returns400 INVALID_REQUESTwithparam: fields, and flatPOSTandPATCH /v1/automations/triggersrefuse the same pair with400. Rename one, or setsyncToContact: falseon one to keep its value off the contact. Fields a fire never copies are exempt:objectandarraycontainers, nested keys,secretfields andsyncToContact: falsefields. - A trigger contract keeps its
emailfield. It needs a top-level{ "key": "email", "type": "string", "required": true }so automations can resolve a recipient. fieldsis optional once a contract is stored. Changing only the enforcement mode is aPUTwith justenforcement, so you never re-send the tree to flip a switch. On a trigger with no stored contract yet, a body withoutfieldsreturns400 INVALID_REQUEST.- The version tracks behavior, not prose. Keys, types,
required, and fallbacks bump it. Editing adescriptionor an example does not. - Mark one-time values
secret. Setsecret: trueon a code, a sign-in link, or a reset token. The value is used only to render the email. It is never stored on the contact, in logs, or in analytics, and it can’t be used in filters, splits, or recipient fields. Scalars only, neveremail.piistill controls how a value is masked in logs, so a field can carry both. See Transactional Email.
off until you turn it on, and the two enforcing modes are prune and
strict.
They differ only in how they treat keys the contract does not declare. prune
drops them, strict fails the payload. Declared-field rules are identical in
both.
Draft a Contract from an Example
Writing a field tree by hand is tedious when you already have the payload. Post a real example toPOST /v1/payload-contracts/infer and Brew types it for you:
date, and
object and array shapes are walked recursively. Every inferred field comes back
required: true, so relax the optional ones yourself.
Inference degrades honestly. A null or an empty array carries no type
evidence, so those land in issues with the offending path instead of a guess.
Nothing is saved either way: review the draft, then PUT it to the trigger’s
/contract.
Dry-Run a Payload
POST /v1/automations/triggers/{triggerEventId}/contract/validate runs a
payload through the same validator the live path uses, against the stored
contract when one exists. Nothing fires, sends, or writes.
valid, the per-field errors and warnings, resolvedPayload with
fallbacks applied, and prunedKeys for anything the contract does not declare.
The optional enforcement field previews prune or strict in place of the
stored mode. That is how you find out what strict would reject before you arm
it.
Pin the Types in SDK Calls
fire accepts a payload type parameter, so call sites compile against the contract:
Fetch the Wiring Brief for an Agent
The trigger read accepts?include=skill, which adds a skill field: a complete SKILL.md-shaped brief (endpoint, auth, the typed contract inline, copy-paste snippets, and a test loop) that a coding agent can follow to wire your service.
SKILL.md in your repo, or hand the URL to an agent. The in-app contract panel offers the same file under Copy as → Download SKILL.md, and it is generated from the same source as the API response.
Preflight Before the First Fire
GET /v1/automations/triggers/{triggerEventId}/readiness runs the same credential, brand-scope, and permission gates a real fire hits, without firing:
details: { ready, blockers[], payloadSchema, endpoint, publishedAutomations, counts }. ready: true means the key, brand scope, and permissions all pass and a fire right now would start at least one run. ready: false with a NO_PUBLISHED_AUTOMATION blocker still answers 200; counts.automations is 0. A real fire returns 422 NO_PUBLISHED_AUTOMATION until a bound automation is published.
Verify Live Fires in the App
Brew checks what your service actually sent against the contract:- A trigger fire’s detail sheet (Events page) shows a Contract check: the raw body replayed through the same validator the live fire used, so a key the fire dropped is labeled exactly as dropped.
- The trigger’s page walks you through wiring with a step list whose completion is derived from real data: a key exists, your test fire arrived, an automation is live.
From an Agent
The MCP server covers the same steps. See MCP Tools.get_trigger_contractreads a contract in any format.infer_payload_contractdrafts one from an example.set_trigger_contractstores it.check_triggerruns the readiness preflight.
Related
- Merge Tags: how templates read payload values.
- Build an Automation: wire a trigger to a flow.
- Errors: every code above.
Need Help?
Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:- Self-Service Tools
- Talk to Our Team
Search Documentation
Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.
Ask ChatGPT or Claude
Click here to open the Copy page menu at the top of this page, then send the page to ChatGPT, Claude, or your editor.