웹훅

ObjectOS는 아웃바운드 웹훅을 위해 영구적인 outbox 모델을 사용합니다. 웹훅 플러그인이 활성화되면 비즈니스 변경 사항이 전달 행을 큐에 추가하고, 백그라운드 디스패처가 재시도와 함께 이를 전달합니다 — 따라서 느리거나 응답하지 않는 수신자가 원래의 트랜잭션을 절대 차단하지 않습니다.

웹훅 활성화

웹훅은 선택적 기능입니다. 배포된 ObjectOS 이미지에는 @objectstack/plugin-webhooks가 포함되어야 하며, 애플리케이션 아티팩트는 웹훅 구독을 등록해야 합니다(일반적으로 sys_webhook 객체의 레코드 형태).

활성화되면 Console에 두 개의 객체가 나타납니다:

전달 시맨틱

• 최소 한 번(At-least-once). 일시적 실패 이후 전달이 재시도될 수 있으므로, 수신자는 멱등성을 보장해야 합니다.
• 영구성(Persistent). 전달 정보는 비즈니스 데이터베이스에 저장되므로 ObjectOS 재시작 후에도 유지됩니다.
• 파티셔닝(Partitioned). 각 디스패처 워커는 outbox의 파티션을 점유하므로, 배포 환경에서 중복 전달 없이 디스패치를 수평으로 확장할 수 있습니다.
• 제한된 재시도(Bounded retries). 실패한 전달은 구성 가능한 상한선까지 백오프와 함께 재시도되며, 소진된 행은 검사를 위해 sys_webhook_delivery에 남습니다.

서명

모든 전달에는 수신자가 라우팅, 중복 제거, 검증할 수 있도록 식별 헤더가 포함됩니다:

X-Objectstack-Event:     <event type, e.g. data.record.created>
X-Objectstack-Delivery:  <delivery id — use as your idempotency key>
X-Objectstack-Attempt:   <attempt number, starting at 1>

웹훅 구독에 secret이 있는 경우, ObjectOS는 모든 요청에 서명도 추가합니다:

X-Objectstack-Signature: sha256=<hex hmac>

서명은 원시 요청 본문에 대해 계산된 HMAC-SHA256(secret, body)입니다. 페이로드를 신뢰하기 전에 수신자에서 이를 검증하십시오:

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

function verify(body, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
  return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

시크릿을 교체하려면 새 시크릿으로 새 구독을 발급하고, 전환 기간 동안 두 구독을 함께 실행한 다음, 이전 구독을 비활성화하십시오.

수신자 기대 사항

• 몇 초 이내에 2xx로 응답하십시오. 408, 429, 또는 5xx 응답(또는 타임아웃/전송 오류)은 재시도 가능하며 백오프와 함께 재시도됩니다. 그 외의 4xx는 영구적 실패로 처리되어 추가 재시도 없이 dead 상태로 이동됩니다.
• 디스패처는 2xx를 확인하기 전까지 전달을 성공으로 표시하지 않으므로, 실패한 수신자의 행은 검사나 재전달을 위해 sys_webhook_delivery에 유지됩니다.
• 멱등성을 보장하십시오 — X-Objectstack-Delivery 헤더(전달 id) 또는 페이로드 내 자체 이벤트 id를 기준으로 중복을 제거하십시오.

실패 처리

문제가 발생하면:

1. 해당 행에 대해 sys_webhook_delivery를 확인하십시오 — status, response_code, response_body, attempts가 기록됩니다.
2. ObjectOS에서 수신자로의 아웃바운드 네트워크 액세스를 확인하십시오.
3. 수신자가 영구적으로 변경된 경우, 구독 URL을 업데이트하고 Console에서 해당 행을 재전달하십시오.
4. 사고 검토 시, 감사 로그(sys_audit_log)는 구독 편집 사항을 기록하지만 페이로드는 기록하지 않습니다 — 페이로드는 outbox에 남습니다.

운영 팁

• 웹훅 URL에 시크릿을 넣지 마십시오(쿼리 문자열은 로그에 기록됩니다).
• 전용 수신자 호스트네임을 사용하면 메인 앱에 영향을 주지 않고 엣지에서 차단하여 부하를 분산할 수 있습니다.
• 디스패처 지연을 모니터링하십시오 — outbox가 계속 증가하는 것은 보통 수신자가 성능 저하 상태임을 의미합니다.