Webhooks
Webhook kết nối dAio với hệ thống của riêng bạn. Thay vì liên tục truy vấn nền tảng, bạn để dAio thông báo cho bạn: ngay khi một sự kiện xảy ra — một cảnh báo thời tiết được kích hoạt, một rủi ro cao được phát hiện — dAio gửi theo thời gian thực một yêu cầu HTTP đã ký đến điểm cuối bạn chọn. Nhờ đó bạn tự động hóa các quy trình của mình: mở phiếu hỗ trợ, thông báo nội bộ, cập nhật bảng điều khiển nghiệp vụ hoặc kích hoạt kế hoạch hành động tại hiện trường.
Đây là cầu nối giữa các cảnh báo của dAio và hệ thống thông tin của bạn.
Mẹo : hãy bắt đầu với một webhook duy nhất đăng ký một loại sự kiện, xác thực toàn bộ chuỗi từ đầu đến cuối, rồi mới mở rộng. Bạn sẽ tránh làm ngập hệ thống bằng thông báo trước khi đã làm cho việc xử lý trở nên đáng tin cậy.
Cấu hình một webhook
- Vào Cài đặt > Webhooks.
- Nhấp vào Webhook mới.
- Nhập URL đích: điểm cuối HTTPS của máy chủ của bạn (ví dụ
https://votre-serveur.com/webhook). - Chọn các sự kiện cần lắng nghe bằng cách nhấp vào các nhãn tương ứng.
- Xác nhận bằng Tạo.
Một khóa bí mật được tạo tự động khi tạo. Nó dùng để ký từng yêu cầu bằng HMAC-SHA256 (xem bên dưới): hãy giữ nó ở phía máy chủ, vì nó cho phép bạn xác minh rằng mỗi lệnh gọi thực sự đến từ dAio.
Lưu ý : URL phải là HTTPS và có thể truy cập công khai. Một điểm cuối dùng HTTP đơn thuần hoặc nằm sau một tường lửa đóng sẽ không thể nhận được các lần gửi.
Các sự kiện khả dụng
| Sự kiện | Mô tả |
|---|---|
weather.alert | Một cảnh báo thời tiết đã được kích hoạt trên một địa điểm |
weather.threshold | Một ngưỡng thời tiết tùy chỉnh đã bị vượt qua |
air_quality.alert | Một cảnh báo chất lượng không khí đã được phát ra |
pollen.alert | Một cảnh báo phấn hoa đã được phát ra |
marine.alert | Một cảnh báo điều kiện biển đã được phát ra |
frost.alert | Một cảnh báo sương giá đã được kích hoạt |
storm.alert | Một cảnh báo giông / bão đã được kích hoạt |
business.risk_high | Một mức rủi ro cao đã được phát hiện cho hoạt động của bạn |
Mẹo : chỉ đăng ký mỗi webhook với những sự kiện thực sự được hệ thống nhận sử dụng. Một điểm cuối «phiếu hỗ trợ» không cần nhận cùng các sự kiện như một điểm cuối «bảng điều khiển».
Định dạng payload
Mỗi lần gửi là một yêu cầu POST có phần thân là một đối tượng JSON. Cấu trúc tổng quát như sau:
{
"event": "weather.alert",
"timestamp": "2026-06-30T08:15:00Z",
"data": {
"site_id": 42,
"site_name": "Entrepôt Nord",
"severity": "high",
"message": "Vent fort attendu (rafales > 80 km/h)"
}
}Trường event xác định loại sự kiện, timestamp cho biết thời điểm phát ra (UTC, định dạng ISO 8601) và data chứa các chi tiết riêng của sự kiện.
Xác thực HMAC-SHA256
Mỗi yêu cầu được ký bằng khóa bí mật của bạn qua HMAC-SHA256. Chữ ký được truyền trong header X-Daio-Signature, theo định dạng sha256=<signature>.
Hãy luôn xác minh chữ ký này trước khi xử lý một yêu cầu: đó là điều bảo đảm rằng lệnh gọi đến từ dAio và payload không bị thay đổi.
Xác minh ở phía máy chủ (Python):
import hmac, hashlib
def verify_webhook(payload, signature, secret):
expected = hmac.new(
secret.encode(), payload, hashlib.sha256
).hexdigest()
return hmac.compare_digest(f"sha256={expected}", signature)Lưu ý : hãy tính chữ ký trên phần thân thô của yêu cầu (các byte nhận được), trước mọi thao tác giải tuần tự hóa JSON. Chỉ một thay đổi định dạng nhỏ nhất cũng làm thay đổi hash và khiến việc xác minh thất bại.
Kiểm thử và gỡ lỗi
- Nhấp vào biểu tượng Kiểm thử (▶) bên cạnh một webhook để gửi một sự kiện giả đến điểm cuối của bạn.
- Một phản hồi HTTP 2xx xác nhận rằng máy chủ của bạn đã nhận và chấp nhận yêu cầu.
- Mở rộng webhook để xem các lần gửi gần nhất: mã HTTP, loại sự kiện và dấu thời gian.
- Một chấm màu cho biết trạng thái của webhook: xanh lá = đang hoạt động, đỏ = bị vô hiệu hóa sau nhiều lần thất bại.
Lịch sử gửi
Mỗi lần gửi đều được ghi nhật ký. Mở rộng một webhook để xem, với mỗi lần thử:
- Mã HTTP phản hồi (xanh nếu < 300, đỏ nếu không)
- Loại sự kiện đã gửi
- Ngày và giờ của lần thử
Một bộ đếm thất bại hiển thị trên webhook khi có các lần gửi bị thất bại.
Thử lại và độ tin cậy
dAio tự động thử gửi lại khi thất bại, với các khoảng thời gian tăng dần. Do đó điểm cuối của bạn phải bất biến (idempotent): cùng một lần gửi có thể đến nhiều lần, và việc xử lý của bạn phải tạo ra cùng một kết quả mà không có tác dụng phụ.
Lưu ý : điểm cuối của bạn phải phản hồi trong vòng 10 giây với mã HTTP 2xx. Vượt quá thời gian đó, hoặc khi có mã lỗi, lần gửi được coi là thất bại và sẽ được thử lại. Sau nhiều lần thất bại, webhook sẽ tự động bị vô hiệu hóa.
Thực hành tốt
- Luôn xác minh chữ ký HMAC trước khi xử lý một payload: đừng bao giờ tin tưởng một yêu cầu chưa được xác thực.
- Phản hồi nhanh: trả về
200ngay lập tức, sau đó xử lý khối lượng công việc ở chế độ nền. Bạn sẽ tránh được hết thời gian chờ và những lần thử lại không cần thiết. - Làm cho việc xử lý của bạn bất biến (idempotent) để hấp thụ an toàn các lần gửi trùng lặp.
- Lọc ngay tại nguồn: chỉ đăng ký mỗi webhook với những sự kiện hữu ích cho hệ thống nhận của nó.
- Theo dõi bộ đếm thất bại và lịch sử gửi để nhanh chóng phát hiện một điểm cuối bị hỏng trước khi nó bị vô hiệu hóa.
- Sử dụng nút Kiểm thử sau mỗi thay đổi ở phía bạn (triển khai, đổi URL) để xác thực chuỗi mà không phải chờ một sự kiện thực.
Mẹo : kết hợp webhook của bạn với các cảnh báo và cấu hình nhóm của bạn để tự động định tuyến đúng thông tin đến đúng hệ thống. Tính khả dụng của webhook phụ thuộc vào gói đăng ký của bạn.