Skip to main content
Connect WorkOS so enterprise auth events fire Brew automations. Welcome new SSO users, confirm password resets, or mirror SCIM provisioning into Brew contacts.
  • Trigger automations from WorkOS events. Cover SSO, SCIM, magic-link, and password reset workflows in one connection.
  • Auto-sync contacts into your audience. Every WorkOS event upserts the user / directory user into Brew with workos-prefixed custom fields you can filter and segment on.
  • Sync SCIM users into Brew contacts. Directory-sync events stream user data straight into your audience without manual import.
  • Confirm sensitive changes. Fire a security confirmation the moment a password reset completes.
Every marketing recipient must have opted in to hear from you. Importing or syncing contact data into Brew is not permission to email it. See What You Can Send.
SCIM matters here. Directory sync provisions employees from a customer’s identity provider, and those people have not opted in to marketing email. Treat synced directory users as transactional and account-notification recipients unless they separately opted in.

How It Works

WorkOS works like every other event source. Brew gives you a webhook URL and verifies each delivery. Each verified event starts the matching Live automations and upserts the user into your audience with workos-prefixed fields. Connected-Source Events has the full model. What’s WorkOS-specific:
  • Brew checks the WorkOS-Signature: t=<timestamp>,v1=<hmac> header against your endpoint’s signing secret, with a 180-second tolerance to block replays.
  • SCIM-provisioned directory users sync as contacts too.
  • A user.updated event re-syncs the contact. A name change in WorkOS reaches Brew even with no automation on that event.

Setup

1

Generate your Brew webhook URL

In Brew, open Integrations, click the WorkOS card, open the Setup tab, and click Generate webhook URL. Copy the URL Brew generates.
2

Create an endpoint in WorkOS

Open dashboard.workos.com, go to Webhooks → Create Endpoint, and paste the Brew URL into the Endpoint URL field.
3

Subscribe to the events Brew supports

Enable user.*, authentication.email_verification_succeeded, authentication.magic_auth_succeeded, authentication.password_failed, password_reset.succeeded, organization.*, organization_membership.*, dsync.user.*, connection.activated, and invitation.accepted, then click Create.Don’t select authentication.*. It subscribes to every WorkOS authentication event, and Brew supports only the three above. Supported Events lists all 18.
4

Copy the endpoint Signing Secret

WorkOS reveals the per-endpoint signing secret on the endpoint detail page. Copy it. The value starts with whsec_.
5

Paste the Signing Secret into Brew

Paste the secret into the Brew connect form and click Connect. Brew verifies every webhook with the WorkOS t=<timestamp>,v1=<hmac> envelope, with a 180-second timestamp tolerance.
6

Send a test event

In WorkOS, open Webhooks, select your endpoint, and click Send test event. Pick user.created and send it. WorkOS signs it automatically.The WorkOS integration page in Brew changes from Waiting for test event to Connected. The test also marks user.created as received in the page’s WorkOS events list.If the page doesn’t connect, click Disconnect on the WorkOS integration page. Then repeat steps 1 and 5 with the secret WorkOS shows.If step 1 shows a different URL from your WorkOS endpoint, update the endpoint. Then send the test again.Brew skips the WorkOS samples it recognizes and lists them as Test event in Manage → Recent events. Brew may treat a sample it doesn’t recognize as a real event. It then adds the sample’s contact and starts any Live automation on that event.Send the test before you set an automation on user.created Live.

Supported Events

Once connected, every WorkOS event below is provisioned automatically and available as a trigger in the automation builder. Brew has no per-event enable step: an event fires when the bound automation is Live. The Manage tab shows:
  • Webhook URL: the URL your WorkOS endpoint points at
  • WorkOS events: how many events Brew has received, and each event’s status
  • Recent events: up to 25 of the newest deliveries that passed the signature check
Once Brew has received an event, it reads Last event and how long ago. It reads No events yet if it hasn’t fired. No events in 90 days means none arrived in the last 90 days, which is how long Brew keeps each delivery. If an event reads No trigger, click Re-provision. Brew supports the following 18 WorkOS events: User
  • user.created
  • user.updated
  • user.deleted
Authentication
  • authentication.email_verification_succeeded
  • authentication.password_failed
  • authentication.magic_auth_succeeded
  • password_reset.succeeded
Organization
  • organization.created (recorded only: it carries no recipient, so Brew starts no automation)
  • organization.updated (recorded only: it carries no recipient, so Brew starts no automation)
  • organization.deleted (recorded only: it carries no recipient, so Brew starts no automation)
Organization membership
  • organization_membership.created
  • organization_membership.updated
  • organization_membership.deleted
Directory sync (SCIM)
  • dsync.user.created
  • dsync.user.updated
  • dsync.user.deleted
Connection
  • connection.activated (recorded only: it carries no recipient, so Brew starts no automation)
Invitation
  • invitation.accepted
password_reset.succeeded is the canonical WorkOS event name. It lives at the top level, not under authentication.*. If you saw authentication.password_reset_succeeded referenced anywhere, that’s an old name no longer used.
In chat, say “Send a security confirmation when a password reset completes”. Brew scaffolds the automation with password_reset.succeeded selected.

Common Patterns

Kind follows What You Can Send. Send transactional email, a direct response to something the person did, from a transactional-purpose domain. Marketing email needs the contact’s opt-in. Both means the confirmation is transactional and the follow-up is marketing. No email means the automation only syncs the contact and sends nothing.

Personalization

These resolve as merge tags in the email body, subject line, and preview text. Use a fallback wherever an empty value would read badly, like {{ firstName | there }}. The trigger. prefix reads the same field, so {{ trigger.firstName }} and {{ firstName }} resolve alike; see Namespaces. Every WorkOS event carries firstName, lastName, and createdAt. The rest are event-specific, and a tag the event doesn’t declare blocks publishing.

Troubleshooting

Open the canvas and confirm at least one automation bound to this event is set to Live (not Draft). The Brew integration’s Manage → Recent events panel confirms the webhook is arriving.If it isn’t there, the issue is upstream (signing secret, clock skew, wrong endpoint URL). A Test event row is a WorkOS Send test event sample, which verifies the webhook and runs nothing.If a real event is there but no email went out, check the automation is published. Then check the contact isn’t unsubscribed or suppressed.From an agent, check_trigger lists what blocks the trigger, and list_trigger_events shows each event’s match state and its runs.
The signing secret in Brew doesn’t match your WorkOS endpoint’s secret. Usually it was rotated in one place but not the other.Copy the current secret from the endpoint detail page in WorkOS. In Brew, click Disconnect on the WorkOS integration page, then repeat setup steps 1 and 5. If step 1 shows a different URL from your WorkOS endpoint, update the endpoint.Then send a test event (step 6). Reconnecting starts the WorkOS events list over.Brew’s 401 body is always Signature verification failed, so WorkOS shows the same reason whatever the cause. A delivery whose timestamp is more than 180 seconds old fails the same check. Re-deliver it from the WorkOS Dashboard once the secret matches.
WorkOS uses password_reset.succeeded (top-level event), not authentication.password_reset_succeeded. Re-subscribe in the WorkOS endpoint to the canonical name.
Don’t rely on Send test event to test an automation. Brew skips the samples it recognizes and may run others like a real event.Build your automation as a Draft, run a test send from the email editor, then publish it to Live. Once it’s Live, trigger its event for yourself, for example a magic-link sign-in. Then watch the Manage → Recent events panel.

From an Agent or Code

Connecting WorkOS, adding the endpoint, and pasting the signing secret are app-only. From an agent or code, the rest is readable and buildable:
  • list_integrations or GET /v1/integrations confirms WorkOS is connected to the brand.
  • check_trigger or GET /v1/automations/triggers/{triggerEventId}/readiness shows whether Brew has received an event and which Live automations consume it.
  • list_trigger_events lists recent deliveries, their match state, and the runs they started.
  • save_automation or POST /v1/automations builds an automation on any event above, and test_automation runs it to one address.
WorkOS fires the events, so fire_trigger_event isn’t used here.

Requirements

  • A WorkOS account with admin access
  • Permission to create webhook endpoints in the WorkOS Dashboard

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.