# WorkOS + Brew

WorkOS의 사용자, 인증, 비밀번호 재설정, 조직, 디렉터리 동기화(SCIM), 연결, 초대 이벤트로 Brew 자동화를 트리거하세요.

정식 URL: https://brew.new/ko/browse/integrations/workos

- 방향: 데이터 가져오기
- 연결 방식: 웹훅 시크릿
- 엔터프라이즈 인증 트리거

## 사용 가능한 기능

- **이벤트 트리거**: WorkOS의 사용자, 인증, 조직, 디렉터리 동기화, 연결 이벤트로 Brew 자동화를 트리거해요.

## WorkOS 이벤트를 유용한 이메일로 바꾸세요

WorkOS를 연결하면 사용자가 생성되거나, 이메일을 인증하거나, 비밀번호를 재설정하거나, 조직에 참여하거나, 디렉터리 동기화로 프로비저닝될 때 브랜드에 맞는 이메일을 보낼 수 있어요. Brew는 WorkOS 이벤트 유형 18개를 자동화 트리거로 바꿔요.

SSO, 디렉터리 동기화, 로그인, 비밀번호 재설정은 계속 WorkOS가 담당해요. Brew는 이벤트를 수신하고, 그 뒤에 이어지는 이메일을 만들어 보내기만 해요.


## 만들 수 있는 것

- 웰컴 이메일: user.created 이벤트는 WorkOS 사용자가 프로비저닝되면 발생해요. authentication.email_verification_succeeded 이벤트는 사용자가 이메일을 인증하면 발생해요. 웰컴 이메일이 두 번 나가지 않도록 트리거는 하나만 고르세요.
- 비밀번호 재설정 확인: password_reset.succeeded 이벤트는 재설정이 완료되면 발생해요. authentication.*에 속하지 않는 WorkOS 최상위 이벤트예요.
- 로그인 알림: authentication.magic_auth_succeeded 이벤트는 매직 링크 로그인이 완료되면, authentication.password_failed 이벤트는 비밀번호 로그인이 실패하면 발생해요. 두 이벤트 모두 사용자를 수신자로 하며, 어느 쪽도 IP 주소나 사용자 에이전트를 개인화 태그로 제공하지 않아요.
- 팀 온보딩: organization_membership.created와 invitation.accepted 이벤트는 모두 누군가 조직에 참여하면 발생하며 role을 담고 있어요. 웰컴 이메일이 두 번 나가지 않도록 트리거는 하나만 고르세요.
- 역할 변경 안내: organization_membership.updated 이벤트는 새 역할처럼 멤버십이 바뀌면 발생해요.
- 디렉터리 동기화 사용자: dsync.user.created, dsync.user.updated, dsync.user.deleted 이벤트로 Brew 연락처를 SCIM 디렉터리와 맞춰 둘 수 있어요.
- 오프보딩 안내: user.deleted와 organization_membership.deleted 이벤트는 사용자가 삭제되거나 조직을 떠나면 발생해요.

## 조직 이벤트와 연결 이벤트로는 이메일이 발송되지 않아요

organization.created, organization.updated, organization.deleted, connection.activated 이벤트에는 수신자가 없어요. Brew는 이 이벤트들을 ‘최근 이벤트’에 수신자를 찾지 못한 것으로 기록하고 자동화를 시작하지 않아요.

새 조직에 관해 사람에게 이메일을 보내려면 organization_membership.created나 invitation.accepted처럼 그 사람의 주소가 담긴 이벤트를 사용하세요.

이메일 주소가 없는 멤버십, 인증, 디렉터리 이벤트라도, Brew가 현재 연결에서 같은 WorkOS 사용자, 멤버십, 디렉터리 사용자의 실제 이메일을 이미 확인했다면 처리될 수 있어요.


## Brew에서 WorkOS 설정하기

- ‘연동’을 열고 WorkOS를 선택한 다음 ‘웹훅 URL 생성’을 누르세요.
- WorkOS 대시보드에서 Webhooks를 열고 엔드포인트를 만든 다음 Brew URL을 붙여 넣으세요.
- 지원되는 이벤트 18개를 구독하세요: user.*, authentication.email_verification_succeeded, authentication.magic_auth_succeeded, authentication.password_failed, password_reset.succeeded, organization.*, organization_membership.*, dsync.user.*, connection.activated, invitation.accepted. authentication.* 전체를 선택하지는 마세요. Brew가 지원하지 않는 인증 이벤트까지 추가돼요.
- 엔드포인트 서명 시크릿을 복사해 Brew에 붙여 넣고 ‘연결’을 누르세요. Brew는 WorkOS 서명 헤더와 180초의 타임스탬프 허용 오차로 각 웹훅을 검증해요.
- WorkOS의 엔드포인트에서 테스트용 user.created 이벤트를 보내세요. Brew의 상태가 ‘테스트 이벤트 대기 중’에서 ‘연결됨’으로 바뀌어요. Brew는 알아볼 수 있는 WorkOS 샘플은 건너뛰지만, 알아보지 못한 샘플은 실제 이벤트처럼 처리할 수 있으니, 그 트리거로 자동화를 게시하기 전에 테스트를 보내세요.
- ‘연결’을 누르면 이벤트 18개 모두에 대한 트리거가 만들어져요. 이벤트별로 켜고 끄는 스위치는 없어요.
- 자동화를 만들고 WorkOS 이벤트를 선택한 다음, 아직 초안일 때 테스트를 보내 보세요. 일치하는 이벤트가 도착하면 활성 상태인 자동화만 실행돼요.

## 지원되는 WorkOS 이벤트

Brew는 다음 이벤트 유형 18개를 지원해요:

- user.created
- user.updated
- user.deleted
- authentication.email_verification_succeeded
- authentication.password_failed
- password_reset.succeeded
- authentication.magic_auth_succeeded
- organization.created
- organization.updated
- organization.deleted
- organization_membership.created
- organization_membership.updated
- organization_membership.deleted
- dsync.user.created
- dsync.user.updated
- dsync.user.deleted
- connection.activated
- invitation.accepted

## 연락처 동기화와 개인화

실제 이메일 주소가 담긴 검증된 이벤트는 자동화에서 쓰이는지와 관계없이, 이메일 주소를 기준으로 Brew 연락처를 만들거나 업데이트해요. 데이터가 있으면 Brew가 이름과 성, workos_user_id, workos_email_verified를 설정해요.

인증 이벤트는 종류에 따라 workos_last_verification_at, workos_last_failed_auth_at, workos_last_password_reset_at, workos_last_magic_auth_at 중 하나를 설정해요. 멤버십 이벤트와 초대 이벤트는 workos_organization_id와 workos_org_role을 설정해요. 디렉터리 이벤트는 workos_directory_user_id와 workos_directory_id를 설정해요.

user.deleted와 dsync.user.deleted 이벤트는 workos_account_status를 deleted로, organization_membership.deleted 이벤트는 removed_from_org로 설정해요. Brew는 연락처를 삭제하지 않아요.

개인화 태그에는 선택한 이벤트에 선언된 페이로드 스키마를 사용하세요. 모든 이벤트에는 값이 있는 경우 email, firstName, lastName, createdAt이 포함돼요. 사용자 이벤트에는 emailVerified가, 조직 이벤트에는 organizationName이, 멤버십 이벤트와 초대 이벤트에는 role이 추가돼요. createdAt은 초 단위 Unix 타임스탬프예요.

WorkOS 객체 ID는 개인화 태그로 쓸 수 없고, 인증 이벤트에 담긴 IP 주소와 사용자 에이전트도 마찬가지예요.

디렉터리 동기화로 들어온 직원은 대개 마케팅 수신에 동의하지 않은 상태예요. 따로 동의하지 않았다면 계정 안내와 트랜잭션 안내만 받는 수신자로 다루세요.


## 이벤트는 들어왔는데 이메일이 발송되지 않는 이유는 뭔가요?

이벤트 수신과 이메일 발송은 별개의 단계예요. 일치하는 자동화가 활성 상태인지 확인한 다음, 필터와 실행 기록, 수신자가 발송 대상인지, 발신 도메인을 확인하세요. 조직 이벤트와 연결 이벤트는 자동화를 시작하지 않으며, Brew가 알아본 WorkOS 테스트 샘플은 테스트 이벤트로 기록돼요.


## 제한 사항 및 문제 해결

- Brew는 WorkOS 사용자, 조직, 디렉터리, 연결을 만들거나 변경할 수 없어요.
- timestamp_invalid:out_of_tolerance와 함께 401 오류가 나면 웹훅의 타임스탬프가 180초 넘게 어긋났다는 뜻이에요. 시계 오차를 확인한 다음 WorkOS 대시보드에서 다시 전송하세요.
- 비밀번호 재설정 자동화가 전혀 실행되지 않으면 엔드포인트가 password_reset.succeeded 이벤트를 구독하고 있는지 확인하세요. WorkOS는 authentication.password_reset_succeeded 이벤트를 보내지 않아요.
- 모든 웹훅이 서명 검증에 실패하면 WorkOS에서 현재 엔드포인트 시크릿을 복사해 다시 연결하세요. 시크릿은 16자 이상이어야 해요.
- 각 이메일의 수신 동의와 목적을 검토하세요. WorkOS 사용자를 동기화했다고 해서 프로모션 이메일을 보내도 되는 건 아니에요.

## 출처 및 설정 가이드

- [WorkOS 설정 가이드](https://docs.brew.new/integrations/import/workos)
- [자동화 만들기](https://docs.brew.new/create-emails/build-an-automation)
- [개인화 태그](https://docs.brew.new/create-emails/merge-tags)
- [Brew로 보낼 수 있는 이메일](https://docs.brew.new/get-started/what-you-can-send)
- [WorkOS 이벤트](https://workos.com/docs/events)

## 관련 링크

- [전체 연동](https://brew.new/ko/browse/integrations.md)
- [회원가입](https://brew.new/ko/sign-up.md)
- 웹사이트: https://brew.new