AiVideoEditor
무료로 시작하기
메뉴

검토 2026-11-11 · API 버전 2026-11-09 · Markdown 읽기

고객 웹훅

워크스페이스의 발신 이벤트 전송이에요. HTTPS 엔드포인트를 등록하고, 일회용 서명 시크릿을 검증하고, 제한된 재시도로 서명된 이벤트를 받으세요.

엔드포인트 등록

curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  $BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
  • 서명 시크릿(whsec_…)은 첫 성공한 생성 응답에서 한 번만 반환돼요. 저장하세요; 같은 생성의 멱등 재생은 시크릿 없이 엔드포인트를 반환하고, 다시 표시될 수 없어요.
  • 수신처는 HTTPS여야 하고, 공개적으로 확인 가능해야 하고, 내장 자격 증명이 없어야 해요. 비공개, 루프백, 링크 로컬(클라우드 메타데이터 포함), unique-local, 멀티캐스트 주소로의 요청은 연결이 만들어지기 전에 거부되고, 리디렉션은 절대 따라가지 않아요.
  • 등록하면 그 엔드포인트를 위한 대상 지정된 webhook.verification 이벤트가 eventTypes 필터와 무관하게 큐에 들어가요. 일반 이벤트는 엔드포인트가 검증에 2xx로 응답한 후에만 흐름돼요.

전송 검증

모든 요청에는 다음이 담겨요:

헤더의미
x-publisher-event-id안정적인 이벤트 ID: 재시도와 재생에서 동일
x-publisher-event-type이벤트 유형, 예: post.published
x-publisher-timestampUnix 초
x-publisher-signaturet=<ts>,v1=<hex>

서명은 서명 시크릿으로 ${t}.${event_id}.${raw_body}에 대한 HMAC-SHA256이에요. ±300초 허용 오차로 검증하고 그 밖의 재생은 거부하세요. Node 예제:

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

function verify(secret, headers, rawBody) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
  if (!m) return false;
  const [t, v1] = [Number(m[1]), m[2]];
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

파싱하기 전에 항상 원본(raw) 요청 본문으로 검증하세요.

이벤트 봉투

{
  "id": "0192d0d0-0000-7000-8000-00000000000f",
  "type": "post.published",
  "createdAt": "2026-11-09T12:00:01Z",
  "apiVersion": "2026-11-09",
  "data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}

초기 이벤트 카탈로그(확장 가능; 등록 시 eventTypes 필터):

  • webhook.verification: 챌린지 페이로드; 엔드포인트를 활성화하려면 2xx로 응답
  • post.published: 하나의 수신처가 네이티브 영수증으로 확정됨
  • delivery.failed: 하나의 수신처가 최종적으로 실패함
  • delivery.requires_action: 동의/재연결/지연 검토 필요

집계 게시물 결과(post.partially_published, post.failed)는 아직 발행되지 않아요; 생산자가 존재할 때만 여기에 문서화돼요, 그러니 의존하지 마세요. 위의 수신처별 이벤트를 구독하고 게시물의 전송 결과에서 배치 상태를 도출하세요.

재시도, 재생, 비활성화

  • 시도: 즉시, 그다음 +1m, +5m, +30m, +2h, +8h. 재시도는 같은 이벤트 ID와 바이트 단위로 동일한 본문을 재사용하므로 안전하게 중복 제거할 수 있어요.
  • 2xx = 전송됨. 429/5xx/타임아웃은 재시도돼요. 다른 4xx는 그 이벤트에 대해 영구 실패예요(엔드포인트를 고친 후 재생하세요).
  • 410 Gone은 엔드포인트를 비활성화해요: 더 이상 이벤트가 큐에 들어가지 않아요.
  • 운영자가 승인한 재생은 내부 웹훅 서비스를 통해 이벤트를 원래 ID로 다시 보내요. 활성 임대 중인 진행 중 시도는 절대 뺏지 않아요; 재생은 이벤트가 사용 중이라고 보고하며 곧 다시 시도할 수 있어요.

운영 노트

  • 전송 진단에는 안전한 결과 코드만 저장돼요: 시크릿, 서명, 요청 헤더, 응답 본문은 절대 저장되지 않아요. 페이로드는 추가로 정화돼요: 제공자/OAuth 시크릿과 미디어 presign URL은 무엇이든 큐에 들어가기 전에 제거돼요.
  • 엔드포인트는 워크스페이스 범위예요: 다른 워크스페이스의 엔드포인트 UUID를 소유해도 아무 일도 일어나지 않아요.
  • 전송은 수락된 이벤트 발생당 최소 한 번이에요; x-publisher-event-id로 중복을 제거하세요.

개발자 도구 가용성

Developers 페이지는 워크스페이스 API 키와 웹훅 엔드포인트를 서명 시크릿 암호화 설정과 무관하게 나열해요. 웹훅 생성에는 유효한 서버 암호화 설정이 필요해요; 설정 경고는 배포 운영자에게 해결을 요청하세요. API 키 관리는 계속 사용 가능해요. 기존 서명 시크릿은 다시 표시되지 않아요.