Direction Map (TL;DR)
For automation run completion, use polling. See Async jobs & polling.
Inbound: You Call Brew
Pattern: Fire a Custom Event
The canonical agent / backend integration path:payload.emailis the contact key. Every trigger’spayloadSchema.fieldsMUST declare{ key: 'email', type: 'string', required: true }. The fire endpoint also upserts the contact from the declared top-level scalar fields the fire sent:firstName/lastName/subscribedland in core columns, and the rest land incustomFieldsunder the key’s folded camelCase name (with the field definition auto-created on the brand). A trigger can’t declare two top-level fields that fold to one contact field, such asplanandPlan; see Typed Payload Contracts. A field withsyncToContact: falsereaches the email only. Object and array fields are not stored on the contact; they stay available to the email as{{ trigger.account.tier }}. A field’sfallbackValuefills the email only and is never written onto the contact (asubscribedfallback only sets the subscription of a new contact). A value the contact field’s type refuses, such as"abc"for anumberfield, is not saved: the rest of the contact is, the automation still runs, and the response’swarnings[]carries{ code: "FIELD_TYPE_MISMATCH", field, expectedType, actualType }.- Use a stable
Idempotency-Keywhen firing from a webhook. See Idempotency for the contract and API design notes for the duplicate-delivery rationale. - The fire endpoint accepts and returns
202, withautomationRunIds[]at the top level (nodetailswrapper),notStarted[]naming any matched automation that could not start and why, and thetriggerInstanceIdfor the fire itself. A replay of the sameIdempotency-Keyanswers200withstatus: "replayed"and the original run ids. Failures use the standard error envelope, so a bad payload is400 INVALID_PAYLOAD. Don’t block on delivery. Poll the run with Async jobs & polling. - At least one bound automation must be Published. Triggers are always-on, but emails only fire when at least one bound automation has
published: true. If every bound automation is in Draft, the fire call returns422 NO_PUBLISHED_AUTOMATION. Publish the automation in the builder (or viabrew.automations.patch({ published: true })) and retry.
Pattern: Integration-Provisioned Triggers
For events that originate inside another product (Clerk’suser.created, Stripe’s customer.subscription.deleted, Shopify’s orders/paid, etc.), Brew can RECEIVE the integration’s webhook directly (no code on your side).
Setup is per-integration in the dashboard (the receiver URL is hosted at /api/integrations/<provider>/webhook/<connectionId>). Once configured, the integration’s events appear in GET /v1/automations/triggers with provider: 'clerk' | 'stripe' | 'shopify' | … and fire your published automations exactly like custom brew_api triggers.
You can bind any of these to an automation. Supported providers today:
Each provider’s adapter normalizes into a flat
{ email, …provider-specific fields } payload that flows through the same fire pipeline as brew_api triggers. Inbound integration webhooks also auto-upsert the contact using a richer per-provider mapper that lands under provider-prefixed camelCase custom field names (for example clerkUserId, stripeCustomerId).
Outbound Email Webhooks
Receive email lifecycle and engagement events at your HTTPS endpoint. Create an endpoint in Settings → Webhooks, or use the public API. Each endpoint belongs to one brand. Organization API keys select the brand withX-Brand-Id;
brand API keys use their existing brand. Management requires the emails scope.
Merging brands that have separate registered webhook configurations currently
requires Brew support. Deleting every endpoint does not remove retained
configuration state or unblock that merge.
Manage in Settings
- Open Settings → Webhooks and choose the brand whose events you want.
- Expand Add webhook endpoint, enter your public HTTPS receiver URL, select the email events, and choose Add endpoint.
- Store the displayed signing secret on your server, then hide it. Verify the unmodified request body before processing a notification.
- Choose a subscribed event beside the endpoint and select Send test event. Test fixtures use example data and do not send an email or change email stats.
- Open Configure and inspect to edit the endpoint and view delivery history. Select a delivery to inspect its payload and HTTP attempts. Use Refresh to check a queued test or replay. Expired payloads cannot be replayed.
- After fixing a receiver, choose Replay webhook for the affected delivery. Replay queues the same notification and confirms that it was accepted; the receiver’s response appears in delivery history.
Open and click signals can come from privacy proxies or security scanners. They
are observations, not proof of a person reading the message. Brew’s reporting
applies its own bot classification and unique counts. Some repeated pixel
refetches are throttled before they create events. Internal mail, test sends and
unsupported event types do not produce customer webhook events.
Create an Endpoint
brew.webhooks and verifyWebhook arrive in the next SDK release; SDK 13.4.0
doesn’t include them. Until then, call the REST routes below and verify with the
svix library.
idempotencyKey in the SDK method’s second argument for the unchanged request.
Use a new key for a changed request or a new creation after confirmed success.
Payload
data.brew.
- Top-level
created_atis event occurrence time.data.created_atis message acceptance time from the delivery mapping or provider payload when available; otherwise it falls back to event occurrence time. data.email_ididentifies one provider message, with a Brew delivery or event ID fallback for failures before provider acceptance. It is not the reusable email design ID. Usedata.brew.design_idanddata.brew.send_idto correlate with Brew resources.- Recipient-specific events include only the affected recipient in
to. - Bounce details use
bounce.type,bounce.subType,bounce.message, and optionalbounce.diagnosticCode, an array of SMTP response strings. Failures usefailed.reason. Link requests useclick.linkand optional tracking metadata. Opens useopen, withtimestamp,ipAddress, anduserAgent. Theemail.openedtest fixture has noopenobject. data.brew.provider_message_idcarries the provider’s message ID on real events, the same value asdata.email_id.- A definitive rejection before provider acceptance emits
email.failedwith a safe reason. Analytics count it as a pre-send skip, so it cannot reduce the pending count of other accepted messages. Rendering, admission, and sender configuration failures do not produce email lifecycle webhooks. - Missing legacy envelope fields are omitted. Message bodies, attachment contents and internal provider metadata are excluded. Secret-rendered subjects and full links are redacted. Secret-rendered messages also omit free-form bounce messages and diagnostic strings, retaining the bounce classification.
Verify Requests
Read the original request body as text before parsing it. Use the endpoint’s signing secret and thesvix-id, svix-timestamp, and svix-signature headers.
verifyWebhook needs no API key, so a receiver does not create a client.
reason says which check failed. Brew adds event types over
time, so acknowledge a type your handler does not know instead of failing it.
You can also verify with the svix library. Store secrets on the server.
Retries and Replay
Delivery is at least once, with no ordering guarantee. Deduplicate on thesvix-id header. data.brew.event_id names the underlying email fact; test
events (data.brew.test: true) all reuse one fixture event_id, so leave them
out if you deduplicate on it. Retries and replays keep the original svix-id,
event identity and payload. Replaying a webhook never sends another email.
Return 2xx within 30 seconds after durably accepting the event. Other statuses,
including redirects, count as failures. The default retry intervals after failed
attempts are 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, and
another 10 hours. Persistently failing endpoints can be disabled automatically.
In Settings → Webhooks, inspect the payload, HTTP response, attempt
history and next retry. Replay a delivery after fixing your receiver. Payloads
for customer events are retained for 30 days; replay is available while provider
retention allows it. Synthetic fixtures contain example data and may follow a
different retention period.
Signing-secret rotation preserves the previous key during the provider’s grace
period so you can update your receiver.
API Operations
eventId in the delivery-history paths is the message id returned by the
webhook events list. List operations accept limit and cursor and use Brew’s
standard pagination envelope. POST operations accept Idempotency-Key.
Synthetic test events have data.brew.test: true and never affect email stats.
Aggregate statistics, deliverability threshold alerts, inbound email, contact and
automation lifecycle webhooks are outside this release.
Related
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.