> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brew.new/llms.txt
> Use this file to discover all available pages before exploring further.

# WorkOS

> Trigger Brew automations from WorkOS user, authentication, password-reset, organization, SCIM, and invitation events across your enterprise auth stack.

Connect [WorkOS](https://workos.com) so enterprise auth events fire Brew automations. Welcome new SSO users, confirm password resets, mirror SCIM provisioning into Brew contacts, or notify ops the moment an SSO connection activates.

## What You Can Do

* **Trigger automations from WorkOS events.** Cover SSO + SCIM + magic-link + password reset workflows in one connection
* **Auto-sync contacts into your audience.** Every WorkOS event upserts the user / directory user into Brew with `workos_*` 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

<Warning>
  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](/get-started/what-you-can-send).
</Warning>

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

1. Brew mints a unique webhook URL for your brand and you paste it into your WorkOS Dashboard.
2. WorkOS signs every webhook with a `WorkOS-Signature: t=<timestamp>,v1=<hmac>` header. Brew verifies the HMAC against your per-endpoint signing secret, with a 180-second timestamp tolerance to block replays.
3. For each verified event Brew (a) starts every **Live** automation whose trigger matches and (b) upserts the WorkOS user (or SCIM-provisioned directory user) into your [audience](/audience/add-contacts) with `workos_*` custom fields.

See [How event triggers work](/integrations/integrations#how-event-triggers-work) for the conceptual flow shared by every event-source integration.

## Setup

<Steps>
  <Step title="Generate your Brew webhook URL">
    In Brew, open **Integrations**, click the **WorkOS** card, and click **Generate URL**. Copy the URL Brew generates.
  </Step>

  <Step title="Create an endpoint in WorkOS">
    Open [dashboard.workos.com](https://dashboard.workos.com), go to **Webhooks → Create Endpoint**, and paste the Brew URL into the **Endpoint URL** field.
  </Step>

  <Step title="Subscribe to the events Brew supports">
    Enable the user, authentication, password\_reset, organization, organization\_membership, dsync.user, connection, and invitation events listed below, then click **Create**.
  </Step>

  <Step title="Copy the endpoint Signing Secret">
    WorkOS reveals the per-endpoint signing secret on the endpoint detail page. Copy it. The value is opaque (no prefix).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Verify it's working">
    Trigger an event in WorkOS (e.g. provision a test user, complete a magic-link sign-in, or run a password reset). Within a few seconds it should appear in the **Manage → Recent events** panel of the WorkOS integration page in Brew. If it doesn't, recheck the signing secret in step 5.
  </Step>
</Steps>

## Triggering Automations

Once connected, every WorkOS event below is provisioned automatically and available as a trigger in the [automation builder](/create-emails/automations). The **Manage** tab is a read-only catalogue plus a live **Recent events** stream, no per-event enable step. Whether an event fires is controlled by whether the bound automation is **Live**.

### Supported Events

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`
* `organization.updated`
* `organization.deleted`

**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`

**Invitation**

* `invitation.accepted`

<Note>
  `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.
</Note>

<Tip>
  In chat, say *"Send a security confirmation when a password reset completes"* and Brew will scaffold the automation with `password_reset.succeeded` pre-selected.
</Tip>

## Common Patterns

| Goal                                        | WorkOS event                                               |
| ------------------------------------------- | ---------------------------------------------------------- |
| Welcome new user                            | `user.created`                                             |
| Real welcome (after email verification)     | `authentication.email_verification_succeeded`              |
| Security confirmation on a password reset   | `password_reset.succeeded`                                 |
| Magic-link sign-in notification             | `authentication.magic_auth_succeeded`                      |
| Welcome the workspace owner                 | `organization.created`                                     |
| Welcome the new teammate                    | `organization_membership.created` or `invitation.accepted` |
| Mirror SCIM provisioning into Brew contacts | `dsync.user.created` / `updated`                           |
| Drop deprovisioned users from audiences     | `dsync.user.deleted`                                       |
| Ops alert when SSO is wired                 | `connection.activated`                                     |

## Personalization

These resolve as [merge tags](/create-emails/merge-tags) in the email body, subject line, and preview text. Use a fallback wherever an empty value would read badly, like `{{ firstName | there }}`.

| Variable                 | Example     |
| ------------------------ | ----------- |
| `{{ firstName }}`        | `Alex`      |
| `{{ lastName }}`         | `Morgan`    |
| `{{ organizationName }}` | `Acme Inc.` |
| `{{ role }}`             | `member`    |
| `{{ emailVerified }}`    | `true`      |

## Troubleshooting

<AccordionGroup>
  <Accordion title="An event arrived but no automation fired" icon="circle-question">
    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). If the event is there but no email sent, the only remaining gate is `automation.published`.
  </Accordion>

  <Accordion title="WorkOS shows 401 with timestamp_invalid:out_of_tolerance" icon="clock">
    Clock skew between WorkOS and Brew exceeds 180 seconds. Verify your platform's clock with `date -u` and re-deliver the webhook from the WorkOS Dashboard.
  </Accordion>

  <Accordion title="Password-reset webhooks don't fire" icon="lock">
    WorkOS uses `password_reset.succeeded` (top-level event), NOT `authentication.password_reset_succeeded`. Re-subscribe in the WorkOS endpoint to the canonical name.
  </Accordion>

  <Accordion title="I want to test before going live" icon="flask">
    Trigger a WorkOS event (e.g. provision a directory user, send yourself a magic link) and watch the **Manage → Recent events** panel. Build your automation as a Draft, run a test send, then publish it to **Live** once you're happy.
  </Accordion>
</AccordionGroup>

## 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:

<Tabs>
  <Tab title="Self-Service Tools">
    <CardGroup cols="2">
      <Card title="Search Documentation" icon="magnifying-glass" color="#c44925">
        Type in the "Ask any question" search bar at the top left to instantly find relevant documentation pages.
      </Card>

      <Card title="ChatGPT/Claude Integration" icon="robot" color="#c44925">
        Click "Open in ChatGPT" at the top right of any page to explore it further with ChatGPT or Claude.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Talk to Our Team">
    <CardGroup cols="2">
      <Card title="Schedule a Call" icon="calendar" color="#c44925" href="https://calendar.google.com/calendar/u/0/appointments/schedules/AcZssZ1iYoRUG1J792XQpbuQLjSRRDupr7MwraFK-HQRCtTYdBmrQi8nZu2qXfzKQigb8gbKJK3KN3-R">
        Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.
      </Card>

      <Card title="Call Us Directly" icon="phone" color="#c44925">
        Need immediate assistance? Reach us at **+1-(332)-203-2145** for urgent issues or time-sensitive questions.
      </Card>

      <Card title="Slack Channel" icon="slack" color="#c44925">
        Our preferred support channel. You'll receive an invite after signup for direct founder support and fast responses.
      </Card>

      <Card title="Email Support" icon="envelope" color="#c44925" href="mailto:support@brew.new">
        Contact us at **[support@brew.new](mailto:support@brew.new)** for detailed inquiries or if you prefer not to use Slack.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>