# Clerk + Brew

Kích hoạt tự động hóa trong Brew từ sự kiện webhook của Clerk khi người dùng đăng ký, tổ chức thay đổi, có gói đăng ký trả phí hoặc có người vào danh sách chờ.

URL chính tắc: https://brew.new/vi/browse/integrations/clerk

- Chiều dữ liệu: Dữ liệu vào
- Kết nối: Webhook secret
- Trình kích hoạt sự kiện xác thực

## Tính năng đang hoạt động

- **Trình kích hoạt sự kiện**: Kích hoạt tự động hóa trong Brew từ 13 sự kiện webhook của Clerk thuộc các nhóm người dùng, tổ chức, thanh toán và danh sách chờ.

## Biến sự kiện Clerk thành email hữu ích

Kết nối Clerk để bắt đầu gửi email chuẩn thương hiệu khi có người đăng ký, gia nhập một tổ chức, bắt đầu gói đăng ký Clerk Billing hoặc vào danh sách chờ của bạn. Clerk ký từng webhook, và Brew biến 13 loại sự kiện thành trình kích hoạt tự động hóa.

Clerk vẫn chịu trách nhiệm về đăng nhập, tổ chức và thanh toán. Brew chỉ lắng nghe sự kiện. Brew không thể thay đổi người dùng, tạo tổ chức hay thu phí gói đăng ký.


## Bạn có thể xây dựng gì

- Email chào mừng: sự kiện user.created xảy ra khi một người dùng mới đăng ký. Bên cạnh họ tên, bạn còn dùng được username, imageUrl và lastSignInAt.
- Hướng dẫn thành viên mới: sự kiện organizationMembership.created mang theo organizationName, organizationSlug và roleName của thành viên mới, dù họ chấp nhận lời mời hay được thêm trực tiếp. organizationInvitation.accepted cũng xảy ra khi có lời mời được chấp nhận, nên hãy chỉ chọn một trình kích hoạt để tránh gửi hai email chào mừng.
- Email tiếp nối lời mời: các sự kiện organizationInvitation.created, organizationInvitation.accepted và organizationInvitation.revoked lấy địa chỉ được mời làm người nhận và mang theo roleName, status và expiresAt. Các sự kiện này không mang theo tên tổ chức, người mời hay liên kết chấp nhận lời mời.
- Email chào mừng người đăng ký: sự kiện subscription.created mang theo planName, planSlug, planAmount, currency, periodStart và periodEnd.
- Nhắc hết hạn dùng thử: sự kiện subscriptionItem.freeTrialEnding xảy ra không lâu trước khi bản dùng thử miễn phí của Clerk Billing chuyển thành gói đăng ký trả phí, kèm planName, planAmount, currency và periodEnd.
- Thông báo quá hạn thanh toán: sự kiện subscriptionItem.pastDue xảy ra khi một mục trong gói đăng ký bị lỡ một lần thanh toán. Hãy dẫn liên kết tới trang thanh toán của riêng bạn.
- Email tiếp nối khi hủy gói hoặc bỏ dở bản dùng thử: sự kiện subscriptionItem.canceled xảy ra khi một mục bị hủy. subscriptionItem.abandoned thường có nghĩa là bản dùng thử đã kết thúc mà chưa có phương thức thanh toán nào được lưu.
- Xác nhận vào danh sách chờ: sự kiện waitlistEntry.created xảy ra khi một địa chỉ email tham gia danh sách chờ Clerk của bạn.

## Sự kiện tổ chức cần xác định được người tạo

Sự kiện organization.created không mang theo địa chỉ email. Brew tra cứu ID người dùng của người tạo trong số các danh tính mà Brew đã ghi nhận ở những sự kiện Clerk trước đó trên kết nối hiện tại. Nếu tìm thấy email thật, sự kiện sẽ được xử lý tiếp. Nếu không, Brew ghi nhận sự kiện là chưa xác định được người nhận, không tạo liên hệ và không khởi chạy tự động hóa nào.

Hãy đăng ký nhận cả sự kiện user.created để Brew biết được địa chỉ của người tạo. Nếu email cần lần nào cũng đến được người nhận, hãy dùng organizationMembership.created, sự kiện có mang theo địa chỉ của thành viên.


## Thiết lập Clerk trong Brew

- Mở mục Tích hợp, chọn Clerk rồi chọn Tạo URL webhook.
- Trong Clerk Dashboard, mở Webhooks và thêm một endpoint dùng URL Brew.
- Đăng ký cho endpoint nhận 13 sự kiện được hỗ trợ trong các nhóm user, organization, organizationInvitation, organizationMembership, paymentAttempt, subscription, subscriptionItem và waitlistEntry, rồi tạo endpoint.
- Hiện signing secret của endpoint (bắt đầu bằng whsec_), dán vào Brew rồi chọn Kết nối. Brew xác minh mọi lần gửi theo đặc tả Standard Webhooks (Svix).
- Trong Clerk, mở thẻ Testing của endpoint, chọn user.created rồi chọn Send Example. Trạng thái trong Brew chuyển từ “Đang chờ sự kiện thử nghiệm” sang “Đã kết nối”. Sự kiện mẫu chỉ dùng để xác minh webhook. Brew không thêm liên hệ và không khởi chạy tự động hóa nào.
- Khi bạn chọn Kết nối, Brew tạo trình kích hoạt cho cả 13 sự kiện. Không có công tắc bật/tắt cho từng sự kiện.
- Tạo một tự động hóa, chọn sự kiện Clerk cho tự động hóa đó rồi gửi thử khi tự động hóa vẫn ở trạng thái Bản nháp. Chỉ những tự động hóa ở trạng thái Đang hoạt động mới chạy khi có sự kiện khớp được gửi đến.

## Các sự kiện Clerk được hỗ trợ

Brew hỗ trợ 13 loại sự kiện sau:

- 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

## Đồng bộ liên hệ và cá nhân hóa

Mỗi sự kiện đã xác minh có địa chỉ email thật đều tạo hoặc cập nhật một liên hệ trong Brew (khớp theo email), bất kể có tự động hóa nào dùng sự kiện đó hay không. Khi có dữ liệu, Brew điền tên, họ và clerk_user_id.

Sự kiện user.created còn điền thêm clerk_username, clerk_image_url, clerk_signed_up_at và clerk_last_sign_in_at. Sự kiện lời mời và thành viên điền clerk_organization_id, clerk_org_role và clerk_org_role_name. Sự kiện lời mời có thêm clerk_org_invitation_status, còn sự kiện thành viên có thêm clerk_organization_name và clerk_organization_slug.

Sự kiện thanh toán điền clerk_subscription_status và clerk_plan_name, một số sự kiện còn có thêm clerk_plan_slug, clerk_subscription_period_end hoặc clerk_is_trialing. Sự kiện paymentAttempt.created điền clerk_last_payment_attempt_status và clerk_last_payment_attempt_at. Sự kiện waitlistEntry.created điền clerk_waitlist_status.

Dùng lược đồ payload đã khai báo của sự kiện được chọn cho thẻ cá nhân hóa. Mọi sự kiện đều có email, firstName, lastName và createdAt. Các trường khác tùy theo sự kiện, chẳng hạn planName, planAmount, roleName, organizationName và grandTotalFormatted. Giá trị planAmount và grandTotalAmount được tính theo đơn vị tiền tệ nhỏ nhất, nên với USD, 2000 tương ứng với 20,00 US$. Dấu thời gian ở dạng Unix, tính bằng giây.

ID đối tượng của Clerk, như ID người dùng, tổ chức và gói đăng ký, không phải là thẻ cá nhân hóa. ID người dùng được lưu trên liên hệ dưới dạng clerk_user_id.

Tài khoản Clerk không đồng nghĩa với việc người dùng đã đồng ý nhận email tiếp thị. Hãy ghi nhận sự đồng ý khi người dùng đăng ký và kiểm tra trước khi gửi email quảng cáo.


## Có thể dùng paymentAttempt.created để gửi email báo thanh toán thất bại không?

Không phải lúc nào cũng được. Brew chỉ nhận sự kiện paymentAttempt.created, chứ không nhận các cập nhật sau đó của lần thử thanh toán này. Trường status có thể là pending, paid hoặc failed, nhưng nếu khoản thanh toán thất bại sau khi lần thử thanh toán đã được tạo, thông tin đó sẽ đến Brew dưới dạng một sự kiện không được hỗ trợ. Với các khoản thanh toán bị lỡ, hãy dùng subscriptionItem.pastDue. Nếu cần hiển thị tổng tiền trong nội dung email, grandTotalFormatted chứa giá trị đã được định dạng sẵn, chẳng hạn $22.00.


## Vì sao sự kiện đã xuất hiện nhưng không có email nào được gửi?

Nhận sự kiện và gửi email là hai bước riêng biệt. Hãy xác nhận có một tự động hóa khớp đang ở trạng thái Đang hoạt động, rồi kiểm tra bộ lọc và lịch sử thực thi của tự động hóa đó, điều kiện của người nhận và tên miền gửi. Lần gửi từ Send Example chỉ xác minh webhook chứ không bao giờ khởi chạy tự động hóa, và sự kiện organization.created không rõ người tạo sẽ được ghi nhận là chưa xác định được người nhận.


## Giới hạn và khắc phục sự cố

- Brew không thể tạo hay thay đổi người dùng, tổ chức hoặc gói đăng ký trên Clerk.
- Chỉ 13 sự kiện được liệt kê mới khởi chạy tự động hóa. Các sự kiện Clerk khác, như cập nhật hoặc xóa người dùng, được ghi nhận là không được hỗ trợ.
- Nếu Clerk báo lỗi 401 ở mọi lần gửi, signing secret trong Brew không khớp với secret của endpoint trong Clerk. Hãy hiện secret đang dùng trong Clerk và kết nối lại bằng secret đó.
- Brew yêu cầu signing secret phải bắt đầu bằng whsec_ và dài ít nhất 24 ký tự.
- Xem lại sự đồng ý và mục đích của từng email. Việc đồng bộ người dùng Clerk không có nghĩa là bạn được phép gửi email quảng cáo.

## Nguồn và hướng dẫn thiết lập

- [Hướng dẫn thiết lập Clerk](https://docs.brew.new/integrations/import/clerk)
- [Tạo một tự động hóa](https://docs.brew.new/create-emails/build-an-automation)
- [Thẻ cá nhân hóa](https://docs.brew.new/create-emails/merge-tags)
- [Những gì bạn có thể gửi bằng Brew](https://docs.brew.new/get-started/what-you-can-send)
- [Tổng quan về webhook của Clerk](https://clerk.com/docs/guides/development/webhooks/overview)

## Liên quan

- [Tất cả tích hợp](https://brew.new/vi/browse/integrations.md)
- [Đăng ký](https://brew.new/vi/sign-up.md)
- Website: https://brew.new