- 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.
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 withworkos-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.updatedevent 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
user.createduser.updateduser.deleted
authentication.email_verification_succeededauthentication.password_failedauthentication.magic_auth_succeededpassword_reset.succeeded
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.createdorganization_membership.updatedorganization_membership.deleted
dsync.user.createddsync.user.updateddsync.user.deleted
connection.activated(recorded only: it carries no recipient, so Brew starts no automation)
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.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
An event arrived but no automation fired
An event arrived but no automation fired
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.WorkOS shows 401 on every delivery
WorkOS shows 401 on every delivery
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.Password-reset webhooks don't fire
Password-reset webhooks don't fire
WorkOS uses
password_reset.succeeded (top-level event), not authentication.password_reset_succeeded. Re-subscribe in the WorkOS endpoint to the canonical name.I want to test before going live
I want to test before going live
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_integrationsorGET /v1/integrationsconfirms WorkOS is connected to the brand.check_triggerorGET /v1/automations/triggers/{triggerEventId}/readinessshows whether Brew has received an event and which Live automations consume it.list_trigger_eventslists recent deliveries, their match state, and the runs they started.save_automationorPOST /v1/automationsbuilds an automation on any event above, andtest_automationruns it to one address.
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:- 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.