webhookFixture — @gj-kit/toss-payments

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

검증된 import 예제

import { webhookFixture } from '@gj-kit/toss-payments/testing';

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

webhookFixture: {
    /**
     * 평탄 구조 DEPOSIT_CALLBACK — eventType·paymentKey 없이 5필드
     * (createdAt/secret/status/transactionKey/orderId)뿐인 실제 형식.
     *
     * verify를 통과시키려면 `depositSecrets.getSecret(orderId)`가 여기 넣은
     * secret과 같은 값을 돌려줘야 한다(승인 시 저장한 Payment.secret 대조 모델).
     * 검증 통과 후 이벤트에는 secret이 남지 않는다(로그 유출 방지 — verifier 규약).
     */
    depositCallback(input: {
        orderId: string;
        secret: string;
        status?: DepositCallbackEvent["status"];
        transactionKey?: string;
    }): WebhookFixturePayload;
    /**
     * 구형 PAYMENT_STATUS_CHANGED — data는 카드 결제 원문 기본값 위에 입력을
     * 덮어쓴 Payment 전체 객체다(입력이 항상 우선 — 상태와 금액의 정합은 호출자 책임).
     *
     * paymentKey/orderId를 raw string으로 받도록 브랜드 필드만 Omit했다 —
     * 설계 문서 표기(`Partial<Payment> & {...}`) 그대로는 교집합이 브랜드 타입을
     * 요구해 plain string 입력이 컴파일 에러가 된다(문서 의도 보존 변형).
     */
    paymentStatusChanged(input: {
        payment: DistributiveOmit<Partial<Payment>, "paymentKey" | "orderId"> & {
            paymentKey: string;
            orderId: string;
            status: "DONE" | "CANCELED" | "PARTIAL_CANCELED" | "ABORTED" | "EXPIRED";
        };
    }): WebhookFixturePayload;
    /**
     * 구형 봉투 {eventType, createdAt, data} 저수준 합성기 — BILLING_DELETED 등
     * 나머지 구형 이벤트와 미지 이벤트(UNKNOWN 전방 호환 경로) 테스트용.
     * data 구조는 검증하지 않는다 — 기대 구조와 다르면 verifier가 UNKNOWN으로 수용한다.
     */
    legacyEvent(eventType: string, data: unknown): WebhookFixturePayload;
    /**
     * 신형 서명 이벤트(payout.changed / seller.changed) — 유효 HMAC 서명 헤더 포함.
     * 생성→검증 왕복으로 SignatureVerified 등급을 테스트한다.
     *
     * ⚠ 설계 문서(§3.6)의 동기 시그니처에서 Promise 반환으로 변형 —
     * 서명 계산이 WebCrypto 전용이라 비동기가 불가피하다({@link signWebhookPayload} 참조).
     */
    signedEvent(input: {
        eventType: "payout.changed" | "seller.changed";
        entityBody: unknown;
        securityKey: SecurityKey;
        transmissionTime?: string;
    }): Promise<WebhookFixturePayload>;
}

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

Release context

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

구현 주석

verify(rawBody, headers) 왕복 테스트용 웹훅 페이로드 합성기.

봉투 3종(구형 {eventType,data} / 평탄 DEPOSIT_CALLBACK / 신형 {eventId,entityBody}) 을 실제 전송 형식(헤더·createdAt 포맷 포함)대로 만든다.