Chuyển đến nội dung
Tài liệu
Nhật ký thay đổiGiáMở bảng điều khiển

Hướng dẫn

Webhooks

Một endpoint webhook nhận những gì các quy tắc cảnh báo của không gian làm việc chuyển tới nó: một bản phát hành bị chặn, một kết quả đang chờ một người, một lần chạy được quản lý đã kết thúc, báo động của một bộ giám sát sản xuất. Mỗi lần gửi là một thân JSON được ký bằng bí mật của endpoint, để máy chủ của bạn kiểm tra rằng nó đến từ không gian làm việc của bạn trước khi xử lý.

Thêm một endpoint

Trên trang Tích hợp của không gian làm việc, một Owner hoặc Admin thêm một webhook có chữ ký với một tên và một URL https công khai trên cổng 443 hoặc 8443. Trang sau đó hiển thị bí mật ký của endpoint, bắt đầu bằng whsec_. Hãy sao chép ngay: bí mật được lưu dưới dạng mã hóa và không hiển thị lại. Để thay thế, hãy xóa endpoint rồi thêm lại.

Sau đó, trên trang Cảnh báo, chọn endpoint làm kênh của một hoặc nhiều quy tắc. "Gửi thử" gửi một lần gửi oloproof.test và hiển thị trạng thái mà máy chủ của bạn trả lời.

Những gì được gửi

{
  "type": "oloproof.gate_blocked",
  "id": "dlv_8c1f0a2b3c4d5e6f7a8b9c0d",
  "created_at": "2026-10-26T14:03:00.000Z",
  "workspace": "acme",
  "rule": { "id": "rul_1a2b3c4d5e6f7a8b9c0d1e2f", "name": "Do not ship" },
  "event": "gate_blocked",
  "items": [
    {
      "project": "support",
      "kind": "run",
      "id": "run_20261026T140100_4f2a",
      "release_action": "BLOCK",
      "rules": [["faithfulness", "FAIL"]],
      "href": "https://oloproof.com/app/workspaces/acme/projects/support/runs/run_20261026T140100_4f2a"
    }
  ],
  "more": 0
}

Một mục chứa các id, trạng thái quyết định của công cụ, hành động phát hành, trạng thái và kết quả của một job, mức, ngưỡng và khoảng của một bộ giám sát đúng như công cụ đã ghi, và các liên kết. Nó không bao giờ chứa đầu vào, đầu ra, câu trả lời mong đợi hay nhãn của một trường hợp. Một lần gửi chứa tối đa 50 mục; more đếm các sự kiện vượt quá số đó.

Xác minh một lần gửi

Mỗi lần gửi mang ba header, theo dạng Standard Webhooks:

  • webhook-id: id của lần gửi, giống nhau ở mọi lần thử lại.
  • webhook-timestamp: thời điểm lần thử này được gửi, tính bằng giây kể từ 1970.
  • webhook-signature: v1, và HMAC-SHA256 mã hóa base64 của id.timestamp.body, với khóa là các byte của bí mật (phần sau whsec_, đã giải mã base64).

Tính chữ ký trên thân thô đúng như đã nhận, so sánh trong thời gian hằng định, và từ chối dấu thời gian lệch quá năm phút so với đồng hồ của bạn.

import base64, hashlib, hmac, time

def verify(secret: str, headers: dict, body: bytes) -> bool:
    key = base64.b64decode(secret.removeprefix("whsec_"))
    msg = f"{headers['webhook-id']}.{headers['webhook-timestamp']}.".encode() + body
    expected = base64.b64encode(hmac.new(key, msg, hashlib.sha256).digest()).decode()
    fresh = abs(time.time() - int(headers["webhook-timestamp"])) <= 300
    given = [part.split(",", 1)[-1] for part in headers["webhook-signature"].split()]
    return fresh and any(hmac.compare_digest(expected, sig) for sig in given)
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, headers, body) {
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const id = headers["webhook-id"], ts = headers["webhook-timestamp"];
  const expected = createHmac("sha256", key).update(`${id}.${ts}.${body}`).digest("base64");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
  return fresh && headers["webhook-signature"].split(" ").some((part) => {
    const sig = Buffer.from(part.split(",").pop());
    return sig.length === expected.length && timingSafeEqual(sig, Buffer.from(expected));
  });
}

Các thư viện Standard Webhooks xác minh cùng những header này.

Gửi

Trả lời bằng bất kỳ trạng thái 2xx nào trong vòng mười giây. Mọi thứ khác, kể cả chuyển hướng, là một lần thử thất bại, được thử lại sau 1, 5, 30, 120 và 360 phút rồi bỏ cuộc. Vì câu trả lời có thể bị mất sau khi máy chủ của bạn đã xử lý, cùng một lần gửi có thể đến hai lần: dùng webhook-id để loại bỏ bản lặp. Một quy tắc kích hoạt nhiều nhất một lần cho mỗi sự kiện, nên một id mới là một lần gửi mới.

Trước mỗi lần thử, tên của endpoint được phân giải lại, và yêu cầu chỉ đi tới một địa chỉ công khai: các địa chỉ loopback, riêng tư, link-local, dùng chung, dành riêng và siêu dữ liệu đám mây bị từ chối, cũng như các dạng IPv6 mang một trong số đó. Kết nối được tạo tới đúng địa chỉ đã được kiểm tra, và chứng chỉ được kiểm tra theo tên.

Slack

Một endpoint Slack là một URL incoming webhook. Nó nhận một tin nhắn ngắn bằng tiếng Anh, một dòng cho mỗi sự kiện, kèm liên kết tới từng kết quả. Slack không kiểm tra các header chữ ký, dù chúng vẫn được gửi.