WebhookVerifier — @gj-kit/toss-payments

@gj-kit/toss-payments/webhook에서 공개하는 interface입니다. package version 0.6.1의 release declaration을 그대로 표시합니다.

검증된 import 예제

import { WebhookVerifier } from '@gj-kit/toss-payments/webhook';

시그니처, 매개변수, 반환 타입

interface WebhookVerifier {
    /**
     * raw body 강제 — 파싱된 객체를 받는 오버로드는 없다(서명 검증 원천 보장).
     * 순서: 헤더 추출 → 봉투 판별 → 진위 검증(일반 이벤트는 sourceIp 필수) →
     * dedupe.claim(진위 통과 후에만) → verdict.
     */
    verify(rawBody: string | Uint8Array, headers: IncomingHeaders, context?: {
        readonly sourceIp?: string;
    }): Promise<Result<WebhookVerdict, WebhookRejection>>;
    /** 수동 verify 경로의 비즈니스 처리 완료 표시. 어댑터는 자동 호출한다. */
    complete(webhook: AcceptedWebhook): Promise<void>;
    /** 수동 verify 경로의 처리 실패 보상. 어댑터는 자동 호출한다. */
    release(webhook: AcceptedWebhook): Promise<void>;
    /**
     * Fetch 표준 어댑터(Next.js Route Handler / Hono) — raw body 추출·검증·dedupe와
     * 처리 완료/실패 claim 전이를 소유한다. 핸들러 완료 후에만 200을 반환하며,
     * options.maxBodyBytes를 넘는 수신 body는 검증 전에 413으로 거부한다.
     */
    fetchHandler(handlers: WebhookHandlers, options?: FetchHandlerOptions): (request: Request) => Promise<Response>;
    /**
     * Express/Node — 모든 content-type을 받는 `express.raw()` 뒤에 장착(JSON 파싱 미들웨어 금지).
     * options.maxBodyBytes를 넘는 수신 body는 검증 전에 413으로 거부한다.
     */
    nodeHandler(handlers: WebhookHandlers, options?: NodeHandlerOptions): (req: NodeIncomingMessageLike, res: NodeServerResponseLike) => Promise<void>;
}

이 선언은 매개변수, optionality, 제네릭, 반환값, 공개 union/type 계약의 정본입니다. 호출 전 필요한 환경·권한·오류 경계는 패키지 Golden path와 이 subpath의 import 조건을 함께 확인하세요.

Release context

• 패키지: @gj-kit/toss-payments
• 버전: 0.6.1
• 공개 entry: ./webhook
• 소스: GitHub