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

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

## 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 **Published** 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 **Published**.

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

| Variable                                       | Example     |
| ---------------------------------------------- | ----------- |
| `{{@trigger:output.payload.firstName}}`        | `Alex`      |
| `{{@trigger:output.payload.lastName}}`         | `Morgan`    |
| `{{@trigger:output.payload.organizationName}}` | `Acme Inc.` |
| `{{@trigger:output.payload.role}}`             | `member`    |
| `{{@trigger:output.payload.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 **Published** (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. Pre-publish your automation as a Draft, run a test send, then flip to Published 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 analyze documentation with ChatGPT or Claude for deeper insights.
      </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>