# Clerk + Brew

사용자 가입, 조직 변경, 유료 구독, 대기자 명단 등록에 관한 Clerk 웹훅 이벤트로 Brew 자동화를 트리거하세요.

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

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

## 사용 가능한 기능

- **이벤트 트리거**: 사용자, 조직, 결제, 대기자 명단 카테고리에 걸친 Clerk 웹훅 이벤트 13개로 Brew 자동화를 트리거해요.

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

Clerk를 연결하면 누군가 가입하거나, 조직에 참여하거나, Clerk Billing 구독을 시작하거나, 대기자 명단에 등록할 때 브랜드에 맞는 이메일을 보낼 수 있어요. Clerk는 모든 웹훅에 서명하고, Brew는 이벤트 유형 13개를 자동화 트리거로 바꿔요.

로그인, 조직, 결제는 계속 Clerk가 담당해요. Brew는 이벤트를 수신하기만 해요. 사용자를 변경하거나, 조직을 만들거나, 구독 요금을 청구할 수는 없어요.


## 만들 수 있는 것

- 웰컴 이메일: user.created 이벤트는 새 사용자가 가입하면 발생해요. 이름 외에 username, imageUrl, lastSignInAt도 쓸 수 있어요.
- 팀 온보딩: organizationMembership.created 이벤트에는 새 멤버의 organizationName, organizationSlug, roleName이 담겨 있어요. 멤버가 초대를 수락했든 직접 추가됐든 마찬가지예요. 초대를 수락하면 organizationInvitation.accepted 이벤트도 발생하므로, 웰컴 이메일이 두 번 나가지 않도록 트리거는 하나만 고르세요.
- 초대 후속 이메일: organizationInvitation.created, organizationInvitation.accepted, organizationInvitation.revoked 이벤트는 초대받은 주소를 수신자로 하며 roleName, status, expiresAt을 담고 있어요. 조직 이름, 초대한 사람, 수락 링크는 담겨 있지 않아요.
- 구독자 웰컴 이메일: subscription.created 이벤트에는 planName, planSlug, planAmount, currency, periodStart, periodEnd가 담겨 있어요.
- 체험 종료 리마인더: subscriptionItem.freeTrialEnding 이벤트는 Clerk Billing 무료 체험이 유료 구독으로 전환되기 직전에 발생하며, planName, planAmount, currency, periodEnd를 담고 있어요.
- 연체 안내: subscriptionItem.pastDue 이벤트는 구독 항목의 결제가 이뤄지지 않으면 발생해요. 이메일에는 자체 결제 페이지 링크를 넣으세요.
- 해지 및 체험 이탈 후속 이메일: subscriptionItem.canceled 이벤트는 구독 항목이 해지되면 발생해요. subscriptionItem.abandoned 이벤트는 보통 등록된 결제 수단 없이 체험이 끝났다는 뜻이에요.
- 대기자 명단 등록 확인: waitlistEntry.created 이벤트는 이메일 주소가 Clerk 대기자 명단에 등록되면 발생해요.

## 조직 이벤트는 생성자를 알아야 처리돼요

organization.created 이벤트에는 이메일 주소가 없어요. Brew는 현재 연결에서 앞서 받은 Clerk 이벤트로 이미 확인한 사용자 중에서 생성자의 사용자 ID를 찾아요. 실제 이메일을 찾으면 이벤트가 그대로 처리돼요. 찾지 못하면 Brew는 이 이벤트를 수신자를 찾지 못한 이벤트로 기록하고, 연락처를 만들지 않으며 자동화도 시작하지 않아요.

Brew가 생성자 주소를 알 수 있도록 user.created 이벤트도 구독하세요. 매번 반드시 사람에게 전달돼야 하는 이메일이라면, 멤버 주소가 담긴 organizationMembership.created 이벤트를 사용하세요.


## Brew에서 Clerk 설정하기

- ‘연동’을 열고 Clerk를 선택한 다음 ‘웹훅 URL 생성’을 누르세요.
- Clerk 대시보드에서 Webhooks를 열고 Brew URL로 엔드포인트를 추가하세요.
- user, organization, organizationInvitation, organizationMembership, paymentAttempt, subscription, subscriptionItem, waitlistEntry 그룹에서 지원 이벤트 13개를 구독 대상으로 선택한 다음 엔드포인트를 만드세요.
- whsec_ 접두사가 붙은 엔드포인트 서명 시크릿을 표시해 Brew에 붙여 넣고 ‘연결’을 누르세요. Brew는 들어오는 모든 웹훅을 Standard Webhooks(Svix) 사양에 따라 검증해요.
- Clerk에서 엔드포인트의 Testing 탭을 열고 user.created 이벤트를 선택한 다음 Send Example 버튼을 누르세요. Brew의 상태가 ‘테스트 이벤트 대기 중’에서 ‘연결됨’으로 바뀌어요. 예시 이벤트는 웹훅을 확인할 뿐이에요. Brew는 연락처를 추가하지 않고 자동화도 시작하지 않아요.
- ‘연결’을 누르면 이벤트 13개 모두에 대한 트리거가 만들어져요. 이벤트별로 켜고 끄는 스위치는 없어요.
- 자동화를 만들고 Clerk 이벤트를 선택한 다음, 아직 초안일 때 테스트를 보내 보세요. 일치하는 이벤트가 도착하면 활성 상태인 자동화만 실행돼요.

## 지원되는 Clerk 이벤트

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

- user.created
- organization.created
- organizationInvitation.created
- organizationInvitation.accepted
- organizationInvitation.revoked
- organizationMembership.created
- paymentAttempt.created
- subscription.created
- subscriptionItem.freeTrialEnding
- subscriptionItem.pastDue
- subscriptionItem.canceled
- subscriptionItem.abandoned
- waitlistEntry.created

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

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

user.created 이벤트는 clerk_username, clerk_image_url, clerk_signed_up_at, clerk_last_sign_in_at도 설정해요. 초대 이벤트와 멤버십 이벤트는 clerk_organization_id, clerk_org_role, clerk_org_role_name을 설정해요. 여기에 초대 이벤트는 clerk_org_invitation_status를, 멤버십 이벤트는 clerk_organization_name과 clerk_organization_slug를 추가해요.

결제 이벤트는 clerk_subscription_status와 clerk_plan_name을 설정하고, 이벤트에 따라 clerk_plan_slug, clerk_subscription_period_end, clerk_is_trialing이 추가되기도 해요. paymentAttempt.created 이벤트는 clerk_last_payment_attempt_status와 clerk_last_payment_attempt_at을 설정해요. waitlistEntry.created 이벤트는 clerk_waitlist_status를 설정해요.

개인화 태그에는 선택한 이벤트에 선언된 페이로드 스키마를 사용하세요. 모든 이벤트에는 email, firstName, lastName, createdAt이 포함돼요. 그 밖의 필드는 이벤트에 따라 다르며, planName, planAmount, roleName, organizationName, grandTotalFormatted 등이 있어요. planAmount와 grandTotalAmount는 통화의 최소 단위로 표시되므로, USD 기준으로 2000은 $20.00에 해당해요. 타임스탬프는 Unix 초 단위예요.

사용자, 조직, 구독 ID 같은 Clerk 객체 ID는 개인화 태그로 쓸 수 없어요. 사용자 ID는 연락처에 clerk_user_id로 저장돼요.

Clerk 계정만으로는 마케팅 이메일 수신 동의가 성립하지 않아요. 가입할 때 수신 동의를 기록하고, 프로모션 이메일을 보내기 전에 확인하세요.


## paymentAttempt.created 이벤트로 결제 실패 이메일을 보낼 수 있나요?

안정적으로 보내기는 어려워요. Brew는 paymentAttempt.created 이벤트만 받고, 이후 결제 시도가 업데이트된 내용은 받지 않아요. status 필드 값은 pending, paid, failed일 수 있지만, 결제 시도가 생성된 뒤에 실패한 결제는 지원하지 않는 이벤트로 Brew에 들어와요. 결제 누락에는 subscriptionItem.pastDue 이벤트를 사용하세요. 이메일 문구에 합계 금액을 넣을 때는 $22.00처럼 미리 서식이 적용된 값이 담긴 grandTotalFormatted를 사용하세요.


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

이벤트 수신과 이메일 발송은 별개의 단계예요. 일치하는 자동화가 활성 상태인지 확인한 다음, 필터와 실행 기록, 수신자가 발송 대상인지, 발신 도메인을 확인하세요. Send Example로 보낸 이벤트는 웹훅을 확인할 뿐 자동화를 시작하지 않으며, 생성자를 알 수 없는 organization.created 이벤트는 수신자를 찾지 못한 것으로 기록돼요.


## 제한 사항 및 문제 해결

- Brew는 Clerk 사용자, 조직, 구독을 만들거나 변경할 수 없어요.
- 목록에 있는 이벤트 13개만 자동화를 시작해요. 사용자 업데이트나 삭제 같은 다른 Clerk 이벤트는 지원하지 않는 이벤트로 기록돼요.
- Clerk에서 모든 전송이 401로 표시되면 Brew의 서명 시크릿이 Clerk의 엔드포인트 시크릿과 일치하지 않는 거예요. Clerk에서 현재 시크릿을 표시해 그 값으로 다시 연결하세요.
- Brew에 넣는 서명 시크릿은 whsec_ 접두사가 붙어 있고 24자 이상이어야 해요.
- 각 이메일의 수신 동의와 목적을 검토하세요. Clerk 사용자를 동기화했다고 해서 프로모션 이메일을 보내도 되는 건 아니에요.

## 출처 및 설정 가이드

- [Clerk 설정 가이드](https://docs.brew.new/integrations/import/clerk)
- [자동화 만들기](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)
- [Clerk 웹훅 개요](https://clerk.com/docs/guides/development/webhooks/overview)

## 관련 링크

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