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:

1. 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.
2. 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.
3. Adapty gửi yêu cầu xác minh đến server của bạn.
4. Server của bạn phản hồi với trạng thái 2XX và nội dung JSON.
5. 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:

1. 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.
2. 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.

Đố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:

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

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

3. Đ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.
   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.
   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.

4. (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.

5. 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.

6. 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, sự kiện hủy gói đăng ký 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ọ.

Cơ chế gửi webhook của Adapty là at-least-once: mỗi sự kiện sẽ được gửi ít nhất một lần, và Adapty sẽ thử lại nếu thất bại thay vì bỏ qua. Nếu mã trạng thái phản hồi từ server của bạn nằm ngoài khoảng 200-404, Adapty sẽ thử gửi lại với cơ chế exponential backoff. Lần thử đầu tiên diễn ra sau khoảng 1 phút kể từ lần thất bại ban đầu, và thời gian chờ sẽ tăng gấp đôi sau mỗi lần — tổng cộng tối đa 9 lần thử trong vòng 24 giờ. Chúng tôi khuyến nghị bạn cấu hình webhook để chỉ thực hiện xác thực cơ bản 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 trả về 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 theo cơ chế bất đồng bộ và phản hồi Adapty thật nhanh. Nếu Adapty không nhận được phản hồi trong vòng 10 giây, lần gửi đó sẽ bị coi là thất bại và sẽ được thử lại.

Các sự kiện không được đảm bảo sẽ đến theo thứ tự — xem Trường sự kiện để biết cách tự sắp xếp thứ tự và loại bỏ trùng lặp.

Tạm dừng phân phối sau nhiều lần thất bại

Khi hầu hết các lần gửi gần đây đến endpoint của bạn thất bại, Adapty sẽ tạm dừng việc gửi webhook cho ứng dụng của bạn. Một lần thất bại ở đây được định nghĩa giống như với các lần thử lại: mã trạng thái phản hồi nằm ngoài khoảng 200-404, lỗi kết nối, hoặc không có phản hồi trong vòng 10 giây. Trong thời gian tạm dừng, Adapty không gửi các sự kiện mới đến endpoint của bạn và cũng không thử lại chúng sau đó. Các sự kiện này sẽ hiển thị trạng thái Sending failed, dù server của bạn chưa nhận được request nào. Sau một khoảng thời gian chờ, Adapty sẽ gửi sự kiện tiếp theo để kiểm tra endpoint. Nếu lần gửi đó thành công, việc gửi sẽ tiếp tục bình thường. Nếu thất bại, việc gửi sẽ bị tạm dừng lại với thời gian chờ dài hơn.

Yêu cầu xác minh mà Adapty gửi khi bạn nhấn Save không đi qua pipeline phân phối này, vì vậy yêu cầu đó có thể thành công ngay cả khi phân phối đang bị tạm dừng.

Để giữ cho quá trình phân phối hoạt động liên tục, hãy phản hồi với trạng thái 2xx cho mọi sự kiện, kể cả những sự kiện mà server của bạn chưa thể khớp với người dùng nào, và xử lý chúng ở phía bạn.