# WorkOS + Brew

Kích hoạt tự động hóa trong Brew từ các sự kiện WorkOS về người dùng, xác thực, đặt lại mật khẩu, tổ chức, đồng bộ thư mục (SCIM), kết nối và lời mời.

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

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

## 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ừ các sự kiện WorkOS về người dùng, xác thực, tổ chức, đồng bộ thư mục và kết nối.

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

Kết nối WorkOS để bắt đầu gửi email chuẩn thương hiệu khi một người dùng được tạo, xác minh email, đặt lại mật khẩu, gia nhập tổ chức hoặc được cấp tài khoản qua đồng bộ thư mục. Brew biến 18 loại sự kiện WorkOS thành trình kích hoạt tự động hóa.

WorkOS vẫn chịu trách nhiệm về SSO, đồng bộ thư mục, đăng nhập và đặt lại mật khẩu. Brew chỉ lắng nghe sự kiện, rồi tạo và gửi các email theo sau những sự kiện đó.


## 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 WorkOS được cấp tài khoản. authentication.email_verification_succeeded xảy ra khi người dùng xác minh email. Hãy chỉ chọn một trình kích hoạt để tránh gửi hai email chào mừng.
- Xác nhận đặt lại mật khẩu: sự kiện password_reset.succeeded xảy ra khi việc đặt lại mật khẩu hoàn tất. Đây là sự kiện cấp cao nhất của WorkOS, không thuộc nhóm authentication.*.
- Thông báo đăng nhập: sự kiện authentication.magic_auth_succeeded xảy ra khi đăng nhập bằng magic link hoàn tất, còn authentication.password_failed xảy ra khi đăng nhập bằng mật khẩu không thành công. Cả hai đều có người nhận là chính người dùng đó, và không sự kiện nào cung cấp địa chỉ IP hay user agent dưới dạng thẻ cá nhân hóa.
- Hướng dẫn thành viên mới: các sự kiện organization_membership.created và invitation.accepted đều xảy ra khi có người gia nhập, và đều mang theo role. Hãy chỉ chọn một trình kích hoạt để tránh gửi hai email chào mừng.
- Thông báo thay đổi vai trò: sự kiện organization_membership.updated xảy ra khi thông tin thành viên tổ chức thay đổi, chẳng hạn khi có vai trò mới.
- Người dùng được đồng bộ thư mục: các sự kiện dsync.user.created, dsync.user.updated và dsync.user.deleted giúp liên hệ trong Brew luôn khớp với thư mục SCIM của bạn.
- Thông báo khi rời đi: các sự kiện user.deleted và organization_membership.deleted xảy ra khi một người dùng bị xóa hoặc rời khỏi tổ chức.

## Sự kiện tổ chức và kết nối không gửi email nào

Các sự kiện organization.created, organization.updated, organization.deleted và connection.activated không mang theo người nhận. Brew ghi các sự kiện này vào mục Sự kiện gần đây với trạng thái chưa xác định được người nhận và không khởi chạy tự động hóa nào.

Để gửi email cho một người về tổ chức mới, hãy dùng một sự kiện có mang theo địa chỉ của họ, chẳng hạn organization_membership.created hoặc invitation.accepted.

Sự kiện về thành viên, xác thực và thư mục không có địa chỉ email vẫn có thể được xử lý tiếp nếu Brew đã ghi nhận email thật cho cùng người dùng WorkOS, cùng bản ghi thành viên hoặc cùng người dùng thư mục trên kết nối hiện tại.


## Thiết lập WorkOS trong Brew

- Mở mục Tích hợp, chọn WorkOS rồi chọn Tạo URL webhook.
- Trong WorkOS Dashboard, mở Webhooks, tạo một endpoint và dán URL Brew.
- Đăng ký nhận 18 sự kiện được hỗ trợ: user.*, authentication.email_verification_succeeded, authentication.magic_auth_succeeded, authentication.password_failed, password_reset.succeeded, organization.*, organization_membership.*, dsync.user.*, connection.activated và invitation.accepted. Đừng chọn authentication.*, vì lựa chọn này thêm cả những sự kiện xác thực mà Brew không hỗ trợ.
- Sao chép signing secret của endpoint, dán vào Brew rồi chọn Kết nối. Brew xác minh từng lần gửi bằng header chữ ký của WorkOS với dung sai dấu thời gian 180 giây.
- Trong WorkOS, gửi một sự kiện user.created thử nghiệm từ endpoint. Trạng thái trong Brew chuyển từ “Đang chờ sự kiện thử nghiệm” sang “Đã kết nối”. Brew bỏ qua các sự kiện mẫu của WorkOS mà Brew nhận ra, nhưng có thể xử lý một sự kiện mẫu không nhận ra như sự kiện thật, vì vậy hãy gửi thử trước khi xuất bản tự động hóa dùng trình kích hoạt đó.
- Khi bạn chọn Kết nối, Brew tạo trình kích hoạt cho cả 18 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 WorkOS 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 WorkOS được hỗ trợ

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

- 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

## Đồ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ọ, workos_user_id và workos_email_verified.

Sự kiện xác thực điền workos_last_verification_at, workos_last_failed_auth_at, workos_last_password_reset_at hoặc workos_last_magic_auth_at. Sự kiện thành viên và lời mời điền workos_organization_id và workos_org_role. Sự kiện thư mục điền workos_directory_user_id và workos_directory_id.

Các sự kiện user.deleted và dsync.user.deleted đặt workos_account_status thành deleted, còn organization_membership.deleted đặt trường này thành removed_from_org. Brew không xóa liên hệ.

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 khi có dữ liệu. Sự kiện người dùng có thêm emailVerified, sự kiện tổ chức có thêm organizationName, còn sự kiện thành viên và lời mời có thêm role. Trường createdAt là dấu thời gian Unix tính bằng giây.

ID đối tượng của WorkOS không phải là thẻ cá nhân hóa, và địa chỉ IP cùng user agent trong sự kiện xác thực cũng vậy.

Nhân viên được đồng bộ từ thư mục thường chưa đồng ý nhận email tiếp thị. Hãy xem họ là người nhận thông báo tài khoản và thông báo giao dịch, trừ khi họ đã đồng ý riêng.


## 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. Sự kiện tổ chức và kết nối không bao giờ khởi chạy tự động hóa, và sự kiện mẫu của WorkOS mà Brew nhận ra sẽ được ghi nhận là sự kiện thử nghiệm.


## 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, thư mục hoặc kết nối trên WorkOS.
- Lỗi 401 kèm timestamp_invalid:out_of_tolerance nghĩa là dấu thời gian của lần gửi lệch quá 180 giây. Hãy kiểm tra độ lệch đồng hồ, rồi gửi lại từ WorkOS Dashboard.
- Nếu tự động hóa đặt lại mật khẩu không bao giờ được kích hoạt, hãy xác nhận endpoint đã đăng ký nhận password_reset.succeeded. WorkOS không bao giờ gửi authentication.password_reset_succeeded.
- Nếu mọi lần gửi đều không vượt qua bước kiểm tra chữ ký, hãy sao chép secret hiện tại của endpoint từ WorkOS và kết nối lại. Brew yêu cầu secret dài ít nhất 16 ký tự.
- Xem lại sự đồng ý và mục đích của từng email. Việc đồng bộ người dùng WorkOS 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 WorkOS](https://docs.brew.new/integrations/import/workos)
- [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)
- [Sự kiện của WorkOS](https://workos.com/docs/events)

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