Skip to main content
Webhooks đẩy sự kiện đến server của bạn nên không phải kiểm tra định kỳ. Đây là cách đáng tin cậy để biết kết quả của các bài đăng đã lên lịch và các lần tải lên bất đồng bộ (video).

​
Đăng ký

Tạo một webhook endpoint trong dashboard tại hub.madiad.com/dashboard/webhooks: nhập URL sẽ nhận các lần phân phối và chọn các loại sự kiện bạn muốn theo dõi. Dashboard sẽ sinh một secret cho endpoint đó, hãy lưu lại. Bạn sẽ dùng giá trị này để xác minh mỗi lần phân phối.

​
Sự kiện

Mỗi lần phân phối là một JSON body dạng { "id", "type", "created_at", "data": { … } }. Với post.completed, data chứa profile_id, platform, media_type, success, url, publish_id và error.

​
Xác minh chữ ký

Mỗi request đều mang header X-MADIAD-Signature ở dạng sha256=<hex>: một HMAC-SHA256 của raw request body, được ký bằng secret đăng ký của bạn. Hãy tính lại và so sánh trước khi tin tưởng payload. Mỗi lần phân phối cũng kèm header X-MADIAD-Event và X-MADIAD-Delivery.
Xác minh dựa trên body thô, chưa qua parse. Việc serialize lại JSON đã parse sẽ thay đổi bytes và chữ ký sẽ không khớp.

​
Phản hồi và thử lại

  • Trả về mã trạng thái 2xx trong vòng 5 giây để xác nhận đã nhận. Hệ thống không đi theo chuyển hướng, nên mã 3xx cũng tính là thất bại.
  • Phản hồi không phải 2xx, hoặc quá thời gian chờ, làm lượt gửi đó thất bại. Mỗi lượt gửi thử nhanh tối đa 3 lần, cách nhau 0,5 giây rồi 1 giây.
  • Mỗi lần phân phối có tối đa 5 lượt gửi. Sau một lượt thất bại, lượt kế tiếp chờ ít nhất 1 phút, rồi 5 phút, 30 phút, 2 giờ. Việc gửi lại chạy theo các đợt xử lý nền nên khoảng cách thực tế có thể dài hơn; muộn nhất là đợt chạy hằng ngày lúc 01:30 UTC (8:30 sáng giờ Việt Nam).
  • Sau lượt thứ 5 vẫn thất bại, lần phân phối bị đánh dấu hỏng và không được gửi lại nữa.
  • Hãy làm cho trình xử lý của bạn idempotent vì một lần phân phối có thể đến nhiều hơn một lần. Khử trùng lặp theo id của lần phân phối (cũng được gửi qua header X-MADIAD-Delivery).
Thực hiện các tác vụ chậm (ghi cơ sở dữ liệu, gọi dịch vụ khác) sau khi bạn đã phản hồi 2xx (ví dụ bằng cách đưa sự kiện vào hàng đợi) để không bao giờ vượt quá thời gian chờ phân phối.