Thiết lập tích hợp webhook

Tích hợp webhook của Adapty bao gồm các bước sau:

Bạn thiết lập endpoint của mình:
1. Đảm bảo server của bạn có thể xử lý các yêu cầu từ Adapty với header Content-Type được đặt thành application/json.
2. Cấu hình server để nhận yêu cầu xác minh từ Adapty và phản hồi với bất kỳ trạng thái 2xx nào kèm theo nội dung JSON.
3. Xử lý các sự kiện gói đăng ký sau khi kết nối được xác minh.
Bạn cấu hình và bật tích hợp webhook trong Adapty Dashboard. Bạn cũng có thể ánh xạ các sự kiện Adapty sang tên sự kiện tùy chỉnh. Chúng tôi khuyến nghị kiểm tra trong môi trường Sandbox trước khi chuyển sang môi trường production.
Adapty gửi yêu cầu xác minh đến server của bạn.
Server của bạn phản hồi với trạng thái 2XX và nội dung JSON.
Sau khi Adapty nhận được phản hồi hợp lệ, hệ thống bắt đầu gửi các sự kiện gói đăng ký.

Thiết lập server để xử lý yêu cầu từ Adapty

Adapty sẽ gửi đến endpoint webhook của bạn 2 loại yêu cầu:

Yêu cầu xác minh: yêu cầu ban đầu để xác minh kết nối đã được thiết lập đúng cách. Yêu cầu này sẽ không chứa bất kỳ sự kiện nào và sẽ được gửi ngay khi bạn nhấn nút Save trong phần tích hợp Webhook của Adapty Dashboard. Để xác nhận endpoint của bạn đã nhận thành công yêu cầu xác minh, endpoint cần phản hồi với thông báo xác minh.
Sự kiện gói đăng ký: yêu cầu tiêu chuẩn mà server Adapty gửi mỗi khi có sự kiện được tạo. Server của bạn không cần phản hồi với bất kỳ nội dung cụ thể nào. Điều duy nhất server Adapty cần là nhận được phản hồi HTTP mã 200 tiêu chuẩn khi nhận tin nhắn thành công.

Yêu cầu xác minh

Sau khi bạn bật tích hợp webhook trong Adapty Dashboard, Adapty sẽ gửi một yêu cầu POST xác minh chứa một đối tượng JSON rỗng {} làm nội dung.

Thiết lập endpoint của bạn với Content-Type header là application/json, tức là endpoint server của bạn cần được cấu hình để nhận các yêu cầu webhook với payload định dạng JSON.

Server của bạn phải phản hồi với mã trạng thái 2xx và gửi bất kỳ phản hồi JSON hợp lệ nào, ví dụ:

{}

Sau khi Adapty nhận được phản hồi xác minh đúng định dạng với mã trạng thái 2xx, tích hợp webhook Adapty của bạn đã được cấu hình hoàn chỉnh.

Sự kiện gói đăng ký

Các sự kiện gói đăng ký được gửi với header Content-Type được đặt thành application/json và chứa dữ liệu sự kiện ở định dạng JSON. Để biết các loại sự kiện và cấu trúc yêu cầu, xem Loại và trường sự kiện Webhook.

Cấu hình tích hợp webhook trong Adapty Dashboard

Trong Adapty, bạn có thể cấu hình các flow riêng biệt cho sự kiện production và sự kiện kiểm thử nhận từ môi trường sandbox của Apple, Stripe hoặc tài khoản thử nghiệm Google.

Adapty hỗ trợ một URL webhook cho mỗi môi trường (production và sandbox). Để chuyển sự kiện đến nhiều dịch vụ, hãy trỏ webhook vào backend của bạn rồi phân phối từ đó.

Đối với sự kiện production, sử dụng trường Production endpoint URL để chỉ định URL mà các callback sẽ được gửi đến. Ngoài ra, hãy cấu hình trường Authorization header value for production endpoint — header này giúp server của bạn xác thực các sự kiện từ Adapty. Lưu ý rằng chúng tôi sẽ sử dụng giá trị được chỉ định trong trường Authorization header value for production endpoint làm header Authorization chính xác như đã nhập, không có bất kỳ thay đổi hay bổ sung nào.

Đối với sự kiện kiểm thử, hãy sử dụng các trường Sandbox endpoint URL và Authorization header value for sandbox endpoint tương ứng.

Để thiết lập tích hợp webhook:

Mở Integrations -> Webhook trong Adapty Dashboard của bạn.

Bật toggle để khởi động tích hợp.

Điền vào các trường tích hợp:

Trường Mô tả

Production endpoint URL URL mà Adapty dùng để gửi các yêu cầu HTTP POST cho sự kiện trong môi trường production.

Trường	Mô tả
Production endpoint URL	URL mà Adapty dùng để gửi các yêu cầu HTTP POST cho sự kiện trong môi trường production.
Authorization header value for production endpoint	Header mà server của bạn sẽ dùng để xác thực các yêu cầu từ Adapty trong môi trường production. Lưu ý rằng chúng tôi sẽ sử dụng giá trị được chỉ định trong trường này làm header `Authorization` chính xác như đã nhập, không có bất kỳ thay đổi hay bổ sung nào. Mặc dù không bắt buộc, nhưng rất khuyến khích thiết lập để tăng cường bảo mật.

Authorization header value for production endpoint

Header mà server của bạn sẽ dùng để xác thực các yêu cầu từ Adapty trong môi trường production. Lưu ý rằng chúng tôi sẽ sử dụng giá trị được chỉ định trong trường này làm header Authorization chính xác như đã nhập, không có bất kỳ thay đổi hay bổ sung nào.

Mặc dù không bắt buộc, nhưng rất khuyến khích thiết lập để tăng cường bảo mật.

Ngoài ra, để phục vụ nhu cầu kiểm thử trong môi trường sandbox, có thêm hai trường khác:

Trường kiểm thử Mô tả

Sandbox endpoint URL URL mà Adapty dùng để gửi các yêu cầu HTTP POST cho sự kiện trong môi trường sandbox.

Trường kiểm thử	Mô tả
Sandbox endpoint URL	URL mà Adapty dùng để gửi các yêu cầu HTTP POST cho sự kiện trong môi trường sandbox.
Authorization header value for sandbox endpoint	Header mà server của bạn sẽ dùng để xác thực các yêu cầu từ Adapty trong quá trình kiểm thử ở môi trường sandbox. Lưu ý rằng chúng tôi sẽ sử dụng giá trị được chỉ định trong trường này làm header `Authorization` chính xác như đã nhập, không có bất kỳ thay đổi hay bổ sung nào. Mặc dù không bắt buộc, nhưng rất khuyến khích thiết lập để tăng cường bảo mật.

Authorization header value for sandbox endpoint

Header mà server của bạn sẽ dùng để xác thực các yêu cầu từ Adapty trong quá trình kiểm thử ở môi trường sandbox. Lưu ý rằng chúng tôi sẽ sử dụng giá trị được chỉ định trong trường này làm header Authorization chính xác như đã nhập, không có bất kỳ thay đổi hay bổ sung nào.

Mặc dù không bắt buộc, nhưng rất khuyến khích thiết lập để tăng cường bảo mật.

(Tùy chọn) Chọn các sự kiện bạn muốn nhận và ánh xạ tên của chúng. Xem Event flows để biết những sự kiện nào được kích hoạt trong các tình huống khác nhau.

Nếu ID sự kiện của bạn khác với ID được dùng trong Adapty, hãy giữ nguyên ID trong hệ thống của bạn và thay thế các ID sự kiện mặc định của Adapty bằng ID của bạn trong phần Events names của trang Integrations -> Webhooks.

ID sự kiện có thể là bất kỳ chuỗi nào; chỉ cần đảm bảo ID sự kiện trong server xử lý webhook của bạn trùng khớp với ID bạn đã nhập trong Adapty Dashboard. Bạn không thể để trống ID sự kiện cho các sự kiện đã được bật.

Các trường và tùy chọn bổ sung không bắt buộc; hãy sử dụng khi cần:

Cài đặt	Mô tả
Send Trial Price	Khi bật, Adapty sẽ bao gồm giá gói đăng ký trong các trường `price_local` và `price_usd` cho sự kiện Trial Started.
Exclude Historical Events	Chọn để loại trừ các sự kiện xảy ra trước khi người dùng cài đặt ứng dụng có tích hợp Adapty SDK. Điều này giúp tránh trùng lặp sự kiện và đảm bảo báo cáo chính xác. Ví dụ: nếu người dùng kích hoạt gói đăng ký hàng tháng vào ngày 10 tháng 1 và cập nhật ứng dụng với Adapty SDK vào ngày 6 tháng 3, Adapty sẽ bỏ qua các sự kiện trước ngày 6 tháng 3 và giữ lại các sự kiện sau đó.
Send user attributes	Bật tùy chọn này để gửi các thuộc tính dành riêng cho người dùng, chẳng hạn như tùy chọn ngôn ngữ. Các thuộc tính này sẽ xuất hiện trong trường `user_attributes`. Xem Trường sự kiện để biết thêm thông tin.
Send attribution	Bật tùy chọn này để bao gồm thông tin attribution (ví dụ: dữ liệu AppsFlyer) trong trường `attributions`. Tham khảo phần Dữ liệu Attribution để biết chi tiết.
Send Play Store purchase token	Bật tùy chọn này để nhận token Play Store cần thiết cho việc xác thực lại giao dịch mua, nếu cần. Khi bật, tham số `play_store_purchase_token` sẽ được thêm vào sự kiện. Để biết chi tiết về nội dung của nó, tham khảo phần Play Store purchase token.

Nhớ nhấn nút Save để xác nhận các thay đổi.

Ngay khi bạn nhấn nút Save, Adapty sẽ gửi yêu cầu xác minh và chờ phản hồi xác minh từ server của bạn.

Chọn sự kiện cần gửi và ánh xạ tên sự kiện

Chọn các sự kiện bạn muốn nhận trên server bằng cách bật toggle bên cạnh sự kiện đó. Nếu tên sự kiện của bạn khác với tên được dùng trong Adapty và bạn cần giữ nguyên tên của mình, bạn có thể thiết lập ánh xạ bằng cách thay thế tên sự kiện mặc định của Adapty bằng tên của bạn trong phần Events names của trang Integrations -> Webhooks.

Tên sự kiện có thể là bất kỳ chuỗi nào. Bạn không thể để trống các trường cho sự kiện đã được bật. Nếu bạn vô tình xóa tên sự kiện Adapty, bạn luôn có thể sao chép tên từ chủ đề Sự kiện gửi đến tích hợp bên thứ ba.

Xử lý sự kiện webhook

Webhook thường được gửi trong vòng 5 đến 60 giây sau khi sự kiện xảy ra. Tuy nhiên, các sự kiện hủy có thể mất đến 2 giờ để được gửi sau khi người dùng hủy gói đăng ký của họ. Nếu mã trạng thái phản hồi của server nằm ngoài khoảng 200-404, Adapty sẽ thử gửi lại với backoff theo cấp số nhân. Lần thử lại đầu tiên xảy ra khoảng 1 phút sau lần thất bại đầu tiên, tăng gấp đôi sau mỗi lần tiếp theo — tối đa 9 lần thử trong vòng 24 giờ. Chúng tôi khuyến nghị bạn thiết lập webhook chỉ thực hiện các xác thực cơ bản đối với nội dung sự kiện từ Adapty trước khi phản hồi. Nếu server của bạn không thể xử lý sự kiện và bạn không muốn Adapty thử lại, hãy sử dụng mã trạng thái trong khoảng 200-404. Ngoài ra, hãy xử lý các tác vụ tốn thời gian một cách bất đồng bộ và phản hồi Adapty nhanh chóng. Nếu Adapty không nhận được phản hồi trong vòng 10 giây, hệ thống sẽ coi đó là lần thất bại và sẽ thử lại.