Chuyển đến nội dung chính
Webhook là một URL do CloudThinker cấp cho bạn. Một hệ thống khác gửi HTTPS POST kèm body JSON tới URL đó, và CloudThinker sẽ chạy một Automation hoặc biến request thành cảnh báo trong Resolve.
Webhook ở đây chỉ là chiều vào. CloudThinker không POST sự kiện ra endpoint của bạn. Để gửi kết quả ra ngoài, hãy dùng thông báo, Slack hoặc Microsoft Teams.

Chọn loại webhook

Có hai loại. Mỗi loại được tạo ở một nơi khác nhau và xử lý request theo cách khác nhau.

Điều kiện tiên quyết

  • Một hệ thống gửi được HTTPS POST với body JSON và header tùy chỉnh.
  • Vai trò Admin của workspace, cho cả hai loại. Developer và Viewer xem được webhook nhưng không tạo được. Xem Người dùng workspace.
  • Với trigger của Automation: một Automation đã có sẵn.
  • Với webhook của Resolve: quyền quản trị trên công cụ giám sát, để bạn thêm webhook vào đó.

Tạo webhook trigger cho Automation

1

Mở Automation

Mở Automation từ trang Automations và tìm phần Triggers.
2

Thêm trigger Webhook

Chọn Webhook. Nếu Automation đã có trigger, hãy nhấn Add another trigger trước, rồi chọn Webhook. CloudThinker tạo trigger ngay và mở hộp thoại Webhook trigger added chứa URL, secret và một Test command sẵn để dán.
3

Sao chép secret

Sao chép URL và secret trước khi chọn Done. Secret chỉ hiển thị một lần.
Mọi URL webhook, ở cả hai loại, đều có dạng:
Trạng thái thành công: thẻ trigger hiển thị webhook, và mỗi lần gọi bạn gửi đều xuất hiện trong danh sách delivery của trigger.
Mất secret? Dùng Rotate webhook secret trên thẻ trigger. URL giữ nguyên, nhưng mọi bên gọi đều cần secret mới.
Công tắc bật/tắt của chính Automation phải bật, nếu không trigger sẽ không khởi động lượt chạy.

Tạo webhook cho Resolve

1

Mở nền tảng

Vào Resolve → Triggers & Outcomes và chọn công cụ của bạn, ví dụ Datadog, Grafana hoặc PagerDuty.
2

Thêm signal

Trong Signals to Resolve, nhấn Add signal. Hộp thoại Create Webhook mở ra với ba bước.
3

Basic Info

Giữ hoặc đổi Webhook Name và thêm Description nếu muốn. Nhấn Next.
4

Configure

Kiểm tra Field Mapping và Severity Mapping. Cả hai đã điền sẵn cho công cụ bạn chọn. Nhấn Next.
5

Advanced

Chọn Auth Method và đặt Auto-investigate. Preset PagerDuty đã chọn sẵn HMAC Signature với HMAC Signature Header là X-PagerDuty-Signature; hãy giữ nguyên header này, nếu không chữ ký của PagerDuty sẽ không qua được bước kiểm tra. Khi bật Auto-investigate, bạn có thể bật thêm Only from a minimum severity (mặc định tắt; khi bật sẽ bắt đầu ở mức High), để các cảnh báo mức thấp hơn không khởi động RCA. Nhấn Create.
Trạng thái thành công: một hộp thoại hiển thị Webhook URL, secret trong Authentication Setup, và Integration Examples. Hãy sao chép URL và secret ngay rồi dán vào công cụ giám sát. Ánh xạ trường, ánh xạ mức độ nghiêm trọng và thời điểm RCA bắt đầu được trình bày trong Webhook signal. Nếu công cụ của bạn không có preset, hãy dùng Nguồn tùy chỉnh.

Xác thực request

Webhook trigger của Automation luôn dùng Bearer token: bên gọi gửi Authorization: Bearer <secret>. Webhook của Resolve cho phép bạn chọn Auth Method. HMAC Signature và API Key chỉ áp dụng cho webhook của Resolve. Bạn đặt tên cả hai header trong bước Advanced. Webhook của Resolve, HMAC Signature. Nếu tự ký request, hãy ký body thô bằng HMAC-SHA256 và gửi digest dưới dạng sha256=<hex> trong header bạn đã đặt (ở đây là header mặc định):
Webhook của Resolve, API Key. Gửi key trong header bạn đã đặt (ở đây là header mặc định):

Gửi gì

Cả hai loại dùng chung một định dạng request. Gửi một JSON object tối đa 1 MB tới URL webhook.

Request

Chi tiết header của webhook Resolve, ngoài phần Xác thực request:
  • HMAC Signature: giá trị là sha256= cộng chuỗi hex chữ thường của HMAC-SHA256 tính trên body thô, với khóa là secret. Khi header đặt là X-PagerDuty-Signature, CloudThinker đọc theo định dạng riêng của PagerDuty: một hoặc nhiều giá trị v1=<hex> phân cách bằng dấu phẩy, chỉ cần một giá trị khớp là đạt.
  • API Key: khi có đặt Key Prefix, giá trị header phải bắt đầu bằng tiền tố đó. CloudThinker bỏ tiền tố và mọi khoảng trắng xung quanh, rồi so phần còn lại với secret.
Body không phải JSON object (một mảng, một chuỗi, hoặc văn bản không phải JSON) bị từ chối với mã 422. CloudThinker không đọc idempotency key, nên mỗi lần bên gửi thử lại đều được tính là một lần gọi mới.

Body: trigger của Automation

JSON object nào cũng được. Toàn bộ body tới agent sau phần hướng dẫn của Automation, nên không cần thiết lập template. Agent thấy tối đa 50.000 ký tự của body; phần vượt quá bị cắt. Body luôn được coi là dữ liệu, không bao giờ là hướng dẫn, nên bên gọi không thể thay đổi những gì agent được yêu cầu làm.

Body: webhook của Resolve

Gửi nguyên payload cảnh báo của công cụ. Field Mapping của webhook lấy các trường từ payload theo đường dẫn JSON, như event.data.title. Ký tự $ ở đầu đường dẫn bị bỏ qua, và mỗi đường dẫn có tối đa 8 đoạn. Giá trị tại đường dẫn severity được chuyển đổi theo Severity Mapping của webhook. Một payload tùy chỉnh tối thiểu:

Amazon SNS

Khi request mang header x-amz-sns-message-type, CloudThinker coi đó là Amazon SNS. CloudThinker kiểm tra chữ ký SNS, tự xác nhận SubscriptionConfirmation, và mở gói Notification để lấy thông điệp bên trong làm body. Cơ chế xác thực của webhook vẫn áp dụng cho mọi request SNS.

Phản hồi

Lần gọi qua được xác thực và kiểm tra hợp lệ nhận HTTP 200 với body sau:
200 nghĩa là CloudThinker đã đưa lần gọi vào hàng đợi. Lượt chạy hoặc cảnh báo diễn ra sau đó một lúc, nên hãy kiểm tra kết quả (xem Kiểm thử bằng curl). Giữ lại request_id nếu bạn cần liên hệ hỗ trợ về một lần gọi. Các kết quả khác ở bảng dưới. Lần gọi qua được xác thực vẫn có thể nhận 400, 413, 422 hoặc 429. Lỗi dùng body {"detail": "..."}.

Kiểm thử bằng curl

Dùng Test command trong hộp thoại Automation, hoặc Integration Examples trong hộp thoại Resolve. Một request Bearer tối thiểu trông như sau:
Kết quả mong đợi: CloudThinker trả về 200 với {"success": true, "request_id": "req_..."}. Kết quả này chỉ chứng minh request đã tới nơi, nên hãy kiểm tra cả kết quả xử lý. Với webhook của Resolve, hãy gửi một cảnh báo thường và một cảnh báo critical, để biết cả hai ánh xạ mức độ nghiêm trọng đều hoạt động. Danh sách delivery của trigger Automation gắn trạng thái cho mỗi lần gọi:

Giới hạn tần suất và lượt chạy bận

Mỗi webhook có giới hạn theo giờ: 60 lần gọi mỗi giờ với trigger của Automation, và mặc định 1.000 lần mỗi giờ với webhook của Resolve. Lần gọi vượt giới hạn vẫn nhận 200 nhưng không khởi động gì, và trigger của Automation liệt kê lần gọi đó là Rate limited. Bên gửi vượt xa giới hạn (gấp 10 lần) sẽ nhận 429. Sau 10 lần xác thực thất bại trong 15 phút, webhook cũng trả về 429 trong một thời gian. Nếu bên gửi phát request dồn dập, hãy gộp sự kiện vào một request hoặc giảm tốc độ. Mỗi Automation chỉ chạy một lượt tại một thời điểm. Lần gọi tới khi đang có lượt chạy sẽ được giữ lại, và CloudThinker thử lại mỗi phút trong tối đa 30 phút. Nếu đang có lượt chạy, lượt chạy của lần gọi được giữ sẽ hiển thị Pending trên tab Runs.
Mỗi trigger chỉ giữ một lần gọi. Lần gọi mới hơn thay thế lần gọi đang giữ, nên các lần gọi giữ trước đó không bao giờ chạy. Nếu sự kiện nào cũng quan trọng, hãy gộp chúng vào một request.
Sau 10 lượt chạy thất bại liên tiếp, CloudThinker tắt Automation và gửi thông báo Automation turned off. Từ đó các lần gọi webhook không còn khởi động lượt chạy cho đến khi bạn sửa nguyên nhân và bật lại.

Khắc phục sự cố

401 nghĩa là thiếu header xác thực, hoặc token trong URL sai; 403 nghĩa là có header nhưng secret hoặc chữ ký không khớp. Trigger của Automation chỉ chấp nhận Authorization: Bearer <secret>. Với webhook của Resolve, hãy so tên header và secret trong công cụ của bạn với Authentication Setup. Sau 10 lần thất bại trong 15 phút, webhook trả về 429 trong một thời gian, nên hãy sửa header trước khi thử lại. Nếu mất secret, dùng Rotate webhook secret trên thẻ trigger (Automation), hoặc mở Resolve → Triggers & Outcomes, chọn công cụ, mở menu của webhook trong Signals to Resolve rồi chọn Regenerate credentials (Resolve). Sau đó cập nhật giá trị mới cho mọi bên gửi.
Hãy ký đúng các byte body thô mà bạn gửi. Định dạng lại hoặc tuần tự hóa lại JSON sau khi ký sẽ làm thay đổi các byte và phá hỏng chữ ký.
Body vượt quá 1 MB. Hãy gửi một bản tóm tắt ngắn kèm liên kết hoặc ID để agent tra cứu, thay vì gửi toàn bộ tài liệu.
Kiểm tra delivery trên thẻ trigger. Rate limited nghĩa là bên gửi quá nhanh. Failed hiển thị nội dung lỗi. Kiểm tra thêm công tắc của Automation đang bật, và xem có lượt chạy Pending đang chờ sau một lượt chạy bận không. Lần gọi Processed mà không có lượt chạy nghĩa là lần gọi đã được giữ lại trong khi có lượt chạy khác, rồi bị lần gọi mới hơn thay thế hoặc bị bỏ sau 30 phút; ghi chú trên thẻ trigger cho biết vì sao lần gọi gần nhất không khởi động lượt chạy. Xem Giới hạn tần suất và lượt chạy bận.
Pulse có thể đã chặn cảnh báo vì coi là nhiễu, hoặc khoảng thời gian đang chọn che mất cảnh báo. Hãy mở rộng khoảng thời gian trên Resolve → Pulse. Nếu signal có mặt nhưng tiêu đề trống hoặc sai mức độ nghiêm trọng, hãy sửa đường dẫn trong Field Mapping hoặc thêm giá trị còn thiếu vào Severity Mapping.
Auto-investigate đang tắt, cảnh báo thấp hơn mức Only from a minimum severity (đặt trong bước Advanced của webhook), hoặc On duty trên Resolve → Investigation đang hiển thị Paused. Hãy kiểm tra cả ba, hoặc tự bắt đầu cuộc điều tra.

Liên quan

Automations

Viết hướng dẫn mà mỗi lần gọi webhook sẽ chạy, và xem lại mọi lượt chạy.

Webhook signal

Ánh xạ các trường cảnh báo và chọn khi nào Resolve tự điều tra.