Skip to main content

웹훅

SecureAI는 Prompt Shield 차단, 카나리아 누출, DLP/PII 사고, API 제한 이벤트, 모델 장애 조치 등 보안 및 플랫폼 이벤트를 자체 HTTP 엔드포인트에 실시간으로 푸시할 수 있습니다. 모든 전송은 HMAC-SHA256 서명으로 서명되므로 SecureAI에서 전송되었으며 변조되거나 재생되지 않았는지 확인할 수 있습니다. 웹훅 엔드포인트는 관리 → 웹훅(API 기반 /api/admin/webhooks)에서 관리자가 관리합니다.

엔드포인트 관리

생성 시간 입력: url, description, events[](이벤트 참조) 및 enabled. 서명 비밀(whsec_...)은 생성 및 교체 시 표시됩니다. 안전하게 저장하세요. 다시 검색할 수 없습니다. 끝점 url은 SSRF 검증을 거쳤습니다. http(s)만 허용되며 인스턴스가 WEBHOOKS_ALLOW_PRIVATE=true로 실행되지 않는 한 개인/루프백/링크 로컬 호스트는 거부됩니다(자체 호스팅 수신기에는 종종 이것이 필요함).

배송 형식

각 전달은 JSON 본문이 포함된 HTTP POST입니다.
헤더는 다음과 같습니다. 전달을 확인하려면 엔드포인트가 2xx 상태를 반환해야 합니다.

서명 확인 중

`${t}.${rawBody}` using your signing secret and compare it to the v1 value. Reject the delivery if it doesn’t match, or if t에 대해 HMAC를 다시 계산하면 허용 범위를 벗어납니다(재생 보호). 원시 요청 본문에 대해 확인 — 먼저 JSON을 구문 분석하고 다시 직렬화하면 바이트가 변경되고 서명이 손상됩니다.

Node.js(익스프레스)

Python(플라스크)

신뢰성

  • 재시도: 0초/10초/60초 백오프로 최대 3회 시도할 수 있으며 각각 5초 시간 제한이 적용됩니다. 2xx은 모두 인정합니다.
  • 자동 비활성화: 20번 연속 전송 실패 후 엔드포인트가 자동으로 비활성화됩니다. 관리자가 이를 다시 활성화합니다(실패 카운터도 재설정됨).
  • 최소 한 번: 전송이 반복될 수 있습니다. X-SecureAI-Delivery(또는 페이로드 id)에서 중복을 제거합니다.
  • Fire-and-forget: 웹훅 전달은 원래 API 요청을 차단하거나 지연하지 않습니다.

관련