Events & Webhooks

Brew’s event model has two directions. You push events INTO Brew today (inbound), and Brew pushes events back to your endpoints on the roadmap (outbound). This page describes what works today and what’s coming.

Direction Map (TL;DR)

Direction	Who calls who	Status
You → Brew: fire a custom event from your backend so Brew runs the matching automation	`POST /v1/automations/triggers/{triggerEventId}/fire { payload, idempotencyKey }`	✅ Shipped
You → Brew: managed integration receivers (Clerk, Stripe, Shopify, Stytch, Supabase, WorkOS, RevenueCat) push their events INTO Brew through a Brew-hosted receive URL you configure once	Per-integration setup in the Integrations tab	✅ Shipped
Brew → You: outbound webhooks for run / send / email-event lifecycle (`run.completed`, `send.delivered`, `send.opened`, …)	Coming: see roadmap	🚧 Planned
Brew → You: SSE / WebSocket streaming for live run logs	Coming with outbound webhooks	🚧 Planned

Until outbound webhooks ship, the supported “wait for completion” pattern is polling. See Async jobs & polling.

Inbound: You Call Brew

Pattern: Fire a Custom Event

The canonical agent / backend integration path:

your-backend → POST  /v1/automations/triggers              → mint triggerEventId
your-backend → POST  /v1/emails                            → mint email bodies (untyped designs)
your-backend → GET   /v1/domains                           → pick verified sending domain
your-backend → POST  /v1/automations                       → assemble graph (trigger → sendEmail → wait → …)
your-backend → PATCH /v1/automations/{automationId}        → { published: true } to go live
your-backend → POST  /v1/automations/triggers/{id}/fire    → fire whenever the real-world event happens

The fire call:

curl -X POST https://brew.new/api/v1/automations/triggers/tri_signup/fire \
  -H "Authorization: Bearer $BREW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-jane@example.com-1779292800" \
  -d '{
    "payload": { "email": "jane@example.com", "firstName": "Jane" }
  }'
# → 202 { triggerInstanceId: "tin_...", triggerEventId: "tri_signup",
#         status: "triggered", automationRunIds: ["run_..."],
#         publishedAutomations: [...], counts: { automations: 1, skipped: 0 },
#         warnings: [], receivedAt: "2026-04-08T12:34:56.789Z" }

Key invariants:

payload.email is the contact key. Every trigger’s payloadSchema.fields MUST 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 / subscribed land in core columns, and the rest land in customFields[key] (with the field definition auto-created on the brand). Object and array fields are not stored on the contact; they stay available to the email as {{ trigger.account.tier }}. A field’s fallbackValue fills the email only and is never written onto the contact (a subscribed fallback only sets the subscription of a new contact). A value the contact field’s type refuses, such as "abc" for a number field, is not saved: the rest of the contact is, the automation still runs, and the response’s warnings[] carries { code: "FIELD_TYPE_MISMATCH", field, expectedType, actualType }.
Use a stable Idempotency-Key when 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, with automationRunIds[] at the top level (no details wrapper), notStarted[] naming any matched automation that could not start and why, and the triggerInstanceId for the fire itself. A replay of the same Idempotency-Key answers 200 with status: "replayed" and the original run ids. Failures use the standard error envelope, so a bad payload is 400 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 returns 422 NO_PUBLISHED_AUTOMATION. Publish the automation in the builder (or via brew.automations.patch({ published: true })) and retry.

Pattern: Integration-Provisioned Triggers

For events that originate inside another product (Clerk’s user.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:

Provider	Common events
Clerk	`user.created`, `organization.created`, `subscription.created`
Stripe	`customer.subscription.created/updated/deleted`, `invoice.paid`, `customer.deleted`
Shopify	`orders/paid`, `customers/create`, `customers/update`
Stytch	`direct.user.create`, `direct.user.delete`, `direct.organization.create`
Supabase	`auth.user.created`, `auth.user.signed_in`, `auth.user.deleted` (auth.users only)
WorkOS	`user.created`, `dsync.user.created`, `organization.created`
RevenueCat	`INITIAL_PURCHASE`, `RENEWAL`, `CANCELLATION`, `EXPIRATION`

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 flat <provider>_* custom field names (e.g. clerk_user_id, stripe_customer_id).

Outbound Webhooks (Roadmap)

We’re shipping outbound webhooks so your backend can be notified when emails are delivered, opened, clicked, bounced, or marked as spam, and when automation runs complete or fail. Below is the planned contract; nothing here is live yet. Subscribe to the changelog for the launch announcement.

Planned Event Types

Event	Fires when
`email.sent`	An email is handed to the upstream ESP.
`email.delivered`	The recipient’s MX accepted the message.
`email.opened`	The recipient opened the message (one event per open).
`email.clicked`	The recipient clicked a tracked link.
`email.bounced`	Hard or soft bounce.
`email.complained`	The recipient marked the message as spam.
`email.unsubscribed`	The recipient unsubscribed via the footer link.
`send.queued`	A `POST /v1/sends` campaign was accepted.
`send.scheduled`	A scheduled send was queued for future delivery.
`send.completed`	All recipients of a send job were handled.
`send.failed`	A send job failed to start (e.g. domain not ready).
`run.started`	An automation run started a workflow.
`run.completed`	A run finished all nodes successfully.
`run.failed`	A run errored out at a node.
`run.canceled`	A run was canceled, whether by `POST /v1/automations/runs/{automationRunId}/cancel` or from the app.
`contact.created` / `contact.updated` / `contact.suppressed`	Contact lifecycle events.
`trigger.fired`	A trigger fire was accepted (before any per-automation routing).

Planned Delivery Contract

Signed. Every webhook will carry an HMAC signature header (X-Brew-Signature) and a timestamp (X-Brew-Timestamp) so you can verify origin.
Retried. Exponential back-off (1s / 5s / 30s / 5m / 1h / 6h) until a 2xx response, then dropped after 24h.
Per-subscription delivery logs. Inspect deliveries + replay failed ones from the dashboard.
Idempotent. Every event carries a unique event.id; consumers should dedupe.

Planned Subscription Management API

None of these paths exist today. /v1/webhook-subscriptions is not in the OpenAPI specification and is not served: every method on it answers 404 NOT_FOUND. The sketch below is a design intent, not a contract, and the names and shapes can still change before launch. Do not write code against it.

POST   /v1/webhook-subscriptions     { url, events: [...], description? }
GET    /v1/webhook-subscriptions
PATCH  /v1/webhook-subscriptions     { subscriptionId, url?, events?, enabled? }
DELETE /v1/webhook-subscriptions     { subscriptionId }
POST   /v1/webhook-subscriptions/rotate-secret { subscriptionId }
GET    /v1/webhook-subscriptions/deliveries?subscriptionId=…  // delivery log

Planned Envelope

{
  "id": "evt_01HZ…",
  "type": "send.delivered",
  "createdAt": "2026-04-08T12:34:56.789Z",
  "data": {
    "sendId": "snd_…",
    "emailId": "eml_promo",
    "recipientEmail": "jane@example.com",
    "messageId": "<resend-msg-id>"
  }
}

What to Do Today

Need	Today’s pattern
React to inbound events (signup, purchase, churn) and run an automation	`POST /v1/automations/triggers/{triggerEventId}/fire`, works now
Wait for a fire to complete	Poll `GET /v1/automations/runs/{automationRunId}`. See Async jobs
Receive provider webhooks (Stripe, Clerk, Shopify, …) into Brew	Configure the integration in the dashboard; Brew hosts the receive URL
Notify your backend when an email opens / delivers	Roadmap: outbound webhooks. Until they ship, use the dashboard analytics, or the ESP’s own webhook (Resend) if you have direct access
Stream live run logs into a UI	Roadmap: SSE. Today: poll `GET /v1/automations/runs/{automationRunId}?include=logs`

Security Checklist (Will Apply When Outbound Webhooks Ship)

Verify the HMAC signature on every webhook (header X-Brew-Signature).
Treat the timestamp as a freshness check: reject deliveries older than 5 minutes.
Dedupe on event.id: Brew may retry on 2xx slowness or your own brief outage.
Return 2xx only when you’ve persisted enough state to survive a restart; return 4xx for permanent rejections so we don’t retry.

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.

ChatGPT/Claude Integration

Click “Open in ChatGPT” at the top right of any page to explore it further with ChatGPT or Claude.

Overview

Core concepts

Guides

MCP server

CLI

Public API v1

Direction Map (TL;DR)

Inbound: You Call Brew

Pattern: Fire a Custom Event

Pattern: Integration-Provisioned Triggers

Outbound Webhooks (Roadmap)

Planned Event Types

Planned Delivery Contract

Planned Subscription Management API

Planned Envelope

What to Do Today

Security Checklist (Will Apply When Outbound Webhooks Ship)

See Also

Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Email Support

​Direction Map (TL;DR)

​Inbound: You Call Brew

​Pattern: Fire a Custom Event

​Pattern: Integration-Provisioned Triggers

​Outbound Webhooks (Roadmap)

​Planned Event Types

​Planned Delivery Contract

​Planned Subscription Management API

​Planned Envelope

​What to Do Today

​Security Checklist (Will Apply When Outbound Webhooks Ship)

​See Also

​Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Email Support

Direction Map (TL;DR)

Inbound: You Call Brew

Pattern: Fire a Custom Event

Pattern: Integration-Provisioned Triggers

Outbound Webhooks (Roadmap)

Planned Event Types

Planned Delivery Contract

Planned Subscription Management API

Planned Envelope

What to Do Today

Security Checklist (Will Apply When Outbound Webhooks Ship)

See Also

Need Help?