Skip to main content
Every payload you send to Brew has a contract: the trigger’s 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):
Every trigger in the brand is included (every page of the trigger list, nothing is truncated), transactional-purpose flows and marketing flows alike. The contract lives on the trigger either way. The output is deterministic, with a content hash in the header:
The CLI reads each trigger’s authoritative /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:
The command exits 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 from GET /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:
The response shape depends on 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:
The exported 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:
Six rules are worth knowing before you write one:
  • 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 object field 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 plan and Plan, or team_size and Team Size, would write one field twice. A PUT declaring such a pair returns 400 INVALID_REQUEST with param: fields, and flat POST and PATCH /v1/automations/triggers refuse the same pair with 400. Rename one, or set syncToContact: false on one to keep its value off the contact. Fields a fire never copies are exempt: object and array containers, nested keys, secret fields and syncToContact: false fields.
  • A trigger contract keeps its email field. It needs a top-level { "key": "email", "type": "string", "required": true } so automations can resolve a recipient.
  • fields is optional once a contract is stored. Changing only the enforcement mode is a PUT with just enforcement, so you never re-send the tree to flip a switch. On a trigger with no stored contract yet, a body without fields returns 400 INVALID_REQUEST.
  • The version tracks behavior, not prose. Keys, types, required, and fallbacks bump it. Editing a description or an example does not.
  • Mark one-time values secret. Set secret: true on 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, never email. pii still controls how a value is masked in logs, so a field can carry both. See Transactional Email.
Declaring a contract does not change what happens at fire time. Enforcement is 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.
While a published automation uses the trigger, changes must stay backward compatible. Enforcement can loosen (strict to prune, prune to off) but not tighten. Removing, retyping, or enum-narrowing a field, or adding a required field without a fallback, is also refused.A refused change returns 409 CONTRACT_LOCKED_BY_PUBLISHED_AUTOMATIONS. To make one, unpublish or detach those automations first.Under prune, a misspelled key is dropped silently and the declared field falls back to its default. Every status signal still reports success, so keep transactional triggers on strict.

Draft a Contract from an Example

Writing a field tree by hand is tedious when you already have the payload. Post a real example to POST /v1/payload-contracts/infer and Brew types it for you:
Integers and floats split automatically, full ISO timestamps become 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.
An invalid payload still returns 200. The verdict is the body, not the status code, so check valid rather than the response status.
Read 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:
A missing required field or a wrong scalar type is a compile error. The wire request is unchanged; the generics are type-level only.

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.
Save the field as 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:
The body is bare, not wrapped in 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.
Together the loop is: generate types, pin them in calls, gate drift in CI, and read the live ledger when something looks off.

From an Agent

The MCP server covers the same steps. See MCP Tools.
  • get_trigger_contract reads a contract in any format.
  • infer_payload_contract drafts one from an example.
  • set_trigger_contract stores it.
  • check_trigger runs the readiness preflight.

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:

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.