Skip to main content
Send events into Brew to run automations. Subscribe to outgoing webhooks to receive email delivery and engagement events in your application.

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:
The fire call:
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 under 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 as plan and Plan; see Typed Payload Contracts. A field with syncToContact: false reaches 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’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: 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 with X-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

  1. Open Settings → Webhooks and choose the brand whose events you want.
  2. Expand Add webhook endpoint, enter your public HTTPS receiver URL, select the email events, and choose Add endpoint.
  3. Store the displayed signing secret on your server, then hide it. Verify the unmodified request body before processing a notification.
  4. 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.
  5. 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.
  6. 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.
Enable/disable, signing-secret rotation and deletion are available on each endpoint. Rotation and deletion ask for confirmation. If endpoint loading fails, use Refresh to retry without changing your configuration. 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.
Endpoints must resolve to public HTTPS addresses. Credentials in URLs, custom ports and redirects are unsupported. Endpoint creation does not backfill historical analytics events. Subscriptions apply when an event is dispatched, so an endpoint created while older dispatch work is pending can receive that work. For a manual retry after an uncertain creation response, pass the same 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

The envelope and event-specific field names follow Resend conventions. Brew extensions live under data.brew.
  • Top-level created_at is event occurrence time. data.created_at is message acceptance time from the delivery mapping or provider payload when available; otherwise it falls back to event occurrence time.
  • data.email_id identifies one provider message, with a Brew delivery or event ID fallback for failures before provider acceptance. It is not the reusable email design ID. Use data.brew.design_id and data.brew.send_id to correlate with Brew resources.
  • Recipient-specific events include only the affected recipient in to.
  • Bounce details use bounce.type, bounce.subType, bounce.message, and optional bounce.diagnosticCode, an array of SMTP response strings. Failures use failed.reason. Link requests use click.link and optional tracking metadata. Opens use open, with timestamp, ipAddress, and userAgent. The email.opened test fixture has no open object.
  • data.brew.provider_message_id carries the provider’s message ID on real events, the same value as data.email_id.
  • A definitive rejection before provider acceptance emits email.failed with 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 the svix-id, svix-timestamp, and svix-signature headers. verifyWebhook needs no API key, so a receiver does not create a client.
Verification rejects altered payloads and timestamps outside a five-minute window; the error’s 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 the svix-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.

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.