WebhookVerifierConfig — @gj-kit/toss-payments

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

검증된 import 예제

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

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

interface WebhookVerifierConfig {
    /** 필수 — 재전송 최대 7회 + 가상계좌 이중 이벤트(PAYMENT_STATUS_CHANGED+DEPOSIT_CALLBACK 동시 구독). */
    readonly dedupe: WebhookDedupeStore;
    /** 키 로테이션(재발급 병행 기간) 대비 배열 — 서명×키 조합 중 1개 일치 시 통과. */
    readonly securityKeys?: readonly SecurityKey[];
    /** 미주입 상태서 DEPOSIT_CALLBACK 수신 → Err missing-config. */
    readonly depositSecrets?: DepositSecretSource;
    /**
     * 기본: 문서 IP 목록({@link TOSS_WEBHOOK_SOURCE_IPS}) 내장. `false` = 끔.
     * 서명·secret이 없는 이벤트는 sourceIp가 없으면 거부한다(fail-closed).
     * 프록시/로드밸런서 뒤에서는 검증된 ingress가 복원한 주소만 전달해야 한다.
     * Unverified 이벤트의 보조 방어선일 뿐 암호학적 검증을 대체하지 않는다.
     *
     * IPv4-mapped IPv6(`::ffff:x.x.x.x`)는 비교 전에 순수 IPv4 표기로 정규화한다 —
     * Node dual-stack 리스너의 `req.socket.remoteAddress`가 이 형태이기 때문(목록 항목
     * 쪽도 동일 정규화). 항목은 순수 IPv4 표기 권장.
     */
    readonly allowedSourceIps?: readonly string[] | false;
    /** 서명 전송 시각의 과거/미래 허용 폭. 기본 5분, false는 비권장 비활성화. */
    readonly transmissionTimeToleranceMs?: number | false;
    /** 테스트와 시계 주입용. */
    readonly clock?: () => Date;
    /**
     * §3.3 이벤트 버스 — webhook.accepted/duplicate/rejected 발행 지점(요약 필드만 —
     * DEPOSIT_CALLBACK rawBody의 secret은 어떤 이벤트 payload에도 실리지 않는다).
     * createTossEvents 산출물만 발행이 흐른다(구조적 모조 객체는 no-op).
     */
    readonly events?: TossEvents;
    /**
     * §3.5 — 설정 시 fetchHandler/nodeHandler의 핸들러 디스패치 직전에
     * 결제 참조가 있는 Unverified 이벤트를 자동 재조회해 `prefetched`로 첨부한다.
     * dedupe 통과분에만 수행(재전송 7회가 조회 7회가 되지 않음).
     * 어댑터는 prefetch와 핸들러가 성공하고 claim을 COMPLETED로 바꾼 뒤에만 200을 반환한다.
     * 빠른 응답이 필요하면 핸들러가 내구적 큐에 적재하는 지점까지 책임져야 한다.
     * 수동 verify() 경로에는 네트워크 호출을 넣지 않으며 trust 등급도 승격하지 않는다.
     */
    readonly autoRefetch?: {
        /** 기존 PaymentLookup 구조적 인터페이스 재사용 — webhook→server 런타임 의존 없음. */
        readonly client: PaymentLookup;
        /** 생략 시 결제 참조 보유 이벤트 전부. 분당 100건 쿼터 방어용 필터. */
        readonly eventTypes?: readonly ('PAYMENT_STATUS_CHANGED' | 'CANCEL_STATUS_CHANGED' | 'ORDER_PAYMENT_STATUS_CHANGED')[];
    };
}

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

Release context

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