웹훅 — Shoal

플래그가 바뀌면 알림을 받고, 서명된 페이로드를 검증합니다.

웹훅은 프로젝트에서 무언가 바뀔 때마다 엔드포인트로 HTTP POST를 보냅니다. 플래그를 켜고 끄거나, 규칙을 고치거나, 출시 단계가 끝났을 때입니다.

엔드포인트 만들기

프로젝트 설정 → 웹훅 → 엔드포인트 추가로 가거나 API를 쓰세요. 받을 이벤트를 고릅니다.

flag.updated: 상태, 규칙, 변형이 바뀜
flag.created, flag.deleted
rollout.step: 예약된 출시가 다음 단계로 넘어감
rollout.guard_triggered: 가드가 출시를 멈추거나 되돌림

페이로드

POST /your/webhook

{
  "id": "evt_01J9ZK4W3T",
  "type": "flag.updated",
  "createdAt": "2026-10-01T08:12:44Z",
  "environment": "production",
  "data": {
    "flag": "new-checkout",
    "changes": [{ "path": "rollout.percent", "from": 25, "to": 50 }],
    "actor": { "type": "user", "email": "mia@acme.dev" }
  }
}

서명 검증

모든 요청에는 Shoal-Signature 헤더가 붙습니다. 원본 본문을 엔드포인트 시크릿으로 HMAC-SHA256한 값이며, 일치하지 않는 요청은 거부하세요.

verify.ts

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(body: string, header: string, secret: string) {
  const expected = createHmac("sha256", secret).update(body).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

verify.py

import hmac, hashlib

def verify(body: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)