Webhook là gì?
Webhook cho phép bạn được thông báo khi các action hệ thống nhất định xảy ra thông qua một lệnh gọi đến URL mà bạn cung cấp. Webhook cũng được gọi là “URL Callbacks” hoặc “HTTP push calls”. URL của bạn phải sử dụng SSL và bắt đầu bằng HTTPS.Webhook Actions
Xem các action có sẵn cho webhook.
Tìm hiểu Ayrshare Webhooks
Webhook được phân loại theo action cụ thể và được đăng ký ở cấp Primary Profile hoặc User Profile. Mọi cập nhật cho Primary hoặc User Profile trước tiên được gửi đến Webhook đã đăng ký cho User Profile. Nếu User Profile không có Webhook đã đăng ký, cập nhật sẽ được gửi đến Webhook đã đăng ký của Primary Profile. Ví dụ:- Nếu một User Profile có Webhook Social Action đã đăng ký và hủy liên kết TikTok, URL Webhook Social Action đã đăng ký cho User Profile sẽ được gọi. Webhook Primary Profile sẽ không được gọi.
- Nếu một User Profile hủy liên kết TikTok và không có Webhook Social Action đã đăng ký, nhưng Primary Profile có Webhook đã đăng ký, URL Webhook Social Action đã đăng ký cho Primary Profile sẽ được gọi.
Đăng ký một Webhook
Đăng ký một Webhook bằng cách cung cấp URL endpoint và loại action cho endpoint POST/hook/webhook. Khi action xảy ra, một HTTP POST sẽ được gửi đến URL được cung cấp.
Ví dụ: đăng ký một URL để nhận thông báo về trạng thái của bài đăng đã lên lịch.
URL endpoint Webhook không nên sử dụng chuyển hướng và phải là URL đích cuối cùng.
Nếu bạn chỉ đăng ký webhook Primary Profile, các User Profile sẽ tự động kế thừa webhook Primary Profile.
Để có webhook duy nhất cho mỗi User Profile, bạn phải đăng ký một webhook cho mỗi User Profile.
Sau khi Webhook của bạn nhận được
HTTP POST, server của bạn phải phản hồi với
trạng thái HTTP là 200 để đánh dấu cuộc gọi là thành công. Nếu server của bạn
không phản hồi trong vòng 15 giây, lần thử được ghi nhận là thất bại và
sẽ được thử lại. Hãy phản hồi ngay khi bạn nhận được yêu cầu và xử lý
bất đồng bộ — timeout không phải là một sự từ chối, vì vậy nếu handler của bạn hoàn thành
công việc nhưng phản hồi muộn, việc thử lại sẽ khiến bạn phải xử lý nó hai lần.Thử lại Webhook
Nếu phản hồi HTTP từ server của bạn không nằm trong phạm vi thành công200-299, hoặc server của bạn không phản hồi trong vòng 15 giây, hệ thống sẽ tự động thử lại cuộc gọi Webhook hai lần nữa. Lần thử lại đầu tiên sẽ xảy ra sau 5 giây và lần thử lại thứ hai sẽ xảy ra 30 giây sau đó. Các lần thử lại sẽ có cùng hookId và cùng payload.
Ngữ nghĩa gửi và Idempotency
Ayrshare gửi webhook ít nhất một lần. Các bản trùng lặp thỉnh thoảng là hoạt động bình thường, không phải là lỗi — mọi consumer đều cần idempotency như một thuộc tính vĩnh viễn. Các bản trùng lặp đến ở hai dạng khác nhau, và mỗi dạng cần một khóa khác nhau:hookId xác định một lần gửi của một sự kiện. Nó giống hệt nhau trong mọi lần thử lại của lần gửi đó, vì vậy claim dựa trên nó khiến việc thử lại an toàn — nhưng một thông báo mới của cùng sự kiện cơ bản sẽ đến với một hookId mới, vì vậy chỉ riêng hookId sẽ không nhận diện được trường hợp đó.
Mẫu bên nhận được đề xuất:
- Phản hồi trước. Trả về
2xxngay lập tức, sau đó xử lý bất đồng bộ. Timeout không phải là sự từ chối — nếu bạn hoàn thành công việc nhưng phản hồi muộn, sự kiện sẽ được gửi lại. - Claim
hookIdmột cách nguyên tử ngay khi yêu cầu đến — một unique constraint, mộtINSERT ... ON CONFLICT DO NOTHING, hoặc mộtSET NX— không phải là một kiểm tra đọc-rồi-ghi. Hai lần thử có thể đến đồng thời, và một guard kiểu kiểm tra-rồi-hành động sẽ cho cả hai đi qua. - Claim thêm một khóa của riêng bạn, được xây dựng từ payload, để một thông báo thứ hai mang một
hookIdmới vẫn được nhận diện. Trênmessages,idkết hợp vớisubActionhoạt động tốt. - Sau đó thực hiện công việc, giữ cả hai claim đủ lâu để bao phủ cửa sổ thử lại và bất kỳ thông báo lại nào sau này.
Chỉ riêng
id của payload không phải là duy nhất cho mọi loại sự kiện — cùng
một message id lặp lại qua các chỉnh sửa và phản ứng, và payload messageRead không mang
id — vì vậy hãy kết hợp nó với subAction thay vì sử dụng nó một cách trơ trọi.Header Metadata Gửi
Mỗi lần gửi đều mang hai header xác định lần truyền cụ thể đó, để bạn có thể phân biệt bản gốc với lần thử lại:X-Ayrshare-Delivery-Attempt là 0 ở lần gửi đầu tiên và tăng thêm một trong mỗi lần thử lại, vì vậy bất kỳ giá trị nào trên 0 đều có nghĩa là chúng tôi đã gửi lần gửi này ít nhất một lần. Hãy xem nó như một bộ đếm không giới hạn thay vì một tập hợp giá trị cố định — số lần thử lại là một chi tiết vận hành có thể thay đổi. X-Ayrshare-Delivery-Id là duy nhất cho mỗi lần thử — hãy trích dẫn nó khi liên hệ hỗ trợ và nó xác định bản ghi gửi chính xác.
Những header này xác định lần truyền; hookId xác định sự kiện. Hãy deduplicate dựa trên hookId, không phải dựa trên delivery id — delivery id được thiết kế là khác nhau trong mọi lần thử, vì vậy sẽ không có gì được nhận diện là trùng lặp.
Bảo mật Webhook
Bạn có thể chọn thêm bảo mật bổ sung bằng cách đặt xác thực HMAC làm HTTP request. Điều này thường được thực hiện để ngăn chặn các cuộc tấn công replay. Ayrshare sử dụng HMAC-SHA256 để hash body của tin nhắn và bao gồm nó và dấu thời gian UNIX trong header của POST.X-Authorization-Content-SHA256 với HMAC-SHA256 của body POST. Signing secret có phạm vi toàn profile — một secret cho mỗi User Profile, được sử dụng trên tất cả các webhook action của profile đó, vì vậy việc đặt nó cho một action sẽ thay đổi nó cho tất cả các action trên profile đó. Các tài khoản đa profile quản lý một secret riêng cho mỗi profile (nhắm mục tiêu một profile với header Profile-Key).