Webhooks

Endpoint webhook menerima apa yang dirutekan kepadanya oleh aturan peringatan ruang kerja: rilis yang diblokir, hasil yang menunggu seseorang, eksekusi terkelola yang berakhir, alarm monitor produksi. Setiap pengiriman adalah badan JSON yang ditandatangani dengan rahasia endpoint, sehingga server Anda dapat memeriksa bahwa pengiriman itu berasal dari ruang kerja Anda sebelum menindaklanjutinya.

Menambahkan endpoint

Di halaman Integrasi ruang kerja, Owner atau Admin menambahkan webhook bertanda tangan dengan nama dan URL https publik pada port 443 atau 8443. Halaman itu lalu menampilkan rahasia penandatanganan endpoint, yang diawali whsec_. Salin saat itu juga: rahasia disimpan terenkripsi dan tidak ditampilkan lagi. Untuk menggantinya, hapus endpoint lalu tambahkan lagi.

Kemudian, di halaman Peringatan, pilih endpoint sebagai saluran untuk satu aturan atau lebih. "Kirim uji" mengirim pengiriman oloproof.test dan menampilkan status yang dijawab server Anda.

Apa yang dikirim

{
  "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
}

Sebuah item memuat id, status keputusan mesin, tindakan rilis, status dan hasil sebuah job, tingkat, ambang, dan interval monitor sebagaimana ditulis mesin, serta tautan. Item tidak pernah memuat input, output, jawaban yang diharapkan, atau label sebuah kasus. Satu pengiriman memuat paling banyak 50 item; more menghitung peristiwa di luar itu.

Memverifikasi pengiriman

Setiap pengiriman membawa tiga header, dalam bentuk Standard Webhooks:

• webhook-id: id pengiriman, sama pada setiap percobaan ulang.
• webhook-timestamp: kapan percobaan ini dikirim, dalam detik sejak 1970.
• webhook-signature: v1, dan HMAC-SHA256 berenkode base64 dari id.timestamp.body, dengan kunci berupa byte rahasia (bagian setelah whsec_, didekode dari base64).

Hitung tanda tangan atas badan mentah sebagaimana diterima, bandingkan dalam waktu konstan, dan tolak stempel waktu yang berselisih lebih dari lima menit dari jam Anda.

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));
  });
}

Pustaka Standard Webhooks memverifikasi header yang sama.

Pengiriman

Jawab dengan status 2xx apa pun dalam sepuluh detik. Selain itu, termasuk pengalihan, adalah percobaan gagal, yang diulang setelah 1, 5, 30, 120, dan 360 menit lalu dihentikan. Karena jawaban bisa hilang setelah server Anda menindaklanjutinya, pengiriman yang sama bisa tiba dua kali: gunakan webhook-id untuk membuang pengulangan. Sebuah aturan terpicu paling banyak sekali untuk setiap peristiwa, jadi id baru berarti pengiriman baru.

Sebelum setiap percobaan, nama endpoint di-resolve ulang, dan permintaan hanya dikirim ke alamat publik: alamat loopback, privat, link-local, bersama, cadangan, dan metadata cloud ditolak, begitu pula bentuk IPv6 yang memuat salah satunya. Koneksi dibuat ke alamat yang telah diperiksa, dan sertifikat diperiksa terhadap nama.

Slack

Endpoint Slack adalah URL incoming webhook. Endpoint ini menerima pesan singkat berbahasa Inggris, satu baris per peristiwa, dengan tautan ke setiap hasil. Slack tidak memeriksa header tanda tangan, yang tetap dikirim.