Webhooks đẩy sự kiện đến server của bạn nên bạ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ý
curl -X POST https://api.madiad.com/v1/webhooks \
-H "Authorization: Bearer $MADIAD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/madiad-webhook",
"events": ["post.published", "post.failed"]
}'
secret, 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
| Sự kiện | Kích hoạt khi |
|---|
post.published | Bài đăng (ngay lập tức hoặc theo lịch) lên sóng trên nền tảng |
post.failed | Nền tảng từ chối bài đăng |
Xác minh chữ ký
Mỗi request đều mang header X-MADIAD-Signature: 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.
import crypto from "node:crypto";
function verify(rawBody, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected),
);
}
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ề status
2xx nhanh chóng (trong vài giây) để xác nhận đã nhận.
- Bất kỳ response không phải
2xx hoặc timeout đều được thử lại với exponential backoff.
- Hãy làm cho handler 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 sự kiện hoặc bài đăng.
Thực hiện các tác vụ chậm (ghi database, gọi downstream) 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á timeout phân phối.
