WebhookVerifier — @gj-kit/toss-payments

A public interface from @gj-kit/toss-payments/webhook. The signature below is taken directly from the 0.6.1 release declaration.

Verified import example

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

Signature, parameters, and return type

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>;
}

This declaration is the source of truth for parameters, optionality, generics, return values, and public union/type contracts. Check the package golden path and this subpath’s import conditions for required environment, permission, and error boundaries before calling it.

Release context

• Package: @gj-kit/toss-payments
• Version: 0.6.1
• Public entry: ./webhook
• Source: GitHub