@portone/server-sdk/dist/webhook.d.ts

PortOne JavaScript SDK for server-side usage

export * from "./generated/webhook/index.js";
import { PortOneError } from "./PortOneError.js";
import type { Webhook } from "./generated/webhook/index.js";
/**
 * SDK에 전달한 사용자 입력이 잘못되었을 경우에 발생하는 에러입니다.
 *
 * 해당 에러는 대부분 사용자의 실수로 발생합니다.
 * 에러가 발생하는 경우, 에러가 발생한 함수의 문서를 참고하여
 * 문제를 수정해주시기 바랍니다.
 */
export declare class InvalidInputError extends PortOneError {
    /** @ignore */
    constructor(message: string);
}
/**
 * 웹훅 검증이 실패했을 때 발생하는 에러입니다.
 *
 * `reason` 필드를 통해 상세한 실패 원인을 확인할 수 있습니다.
 */
export declare class WebhookVerificationError extends PortOneError {
    /**
     * 웹훅 검증이 실패한 상세 사유을 나타냅니다.
     */
    readonly reason: WebhookVerificationFailureReason;
    /**
     * 웹훅 검증 실패 사유로부터 에러 메시지를 생성합니다.
     *
     * @param reason 에러 메시지를 생성할 실패 사유
     * @returns 에러 메시지
     */
    static getMessage(reason: WebhookVerificationFailureReason): string;
    /** @ignore */
    constructor(reason: WebhookVerificationFailureReason, options?: ErrorOptions);
}
/**
 * 웹훅 검증 실패 사유입니다.
 *
 * `WebhookVerificationError.getMessage()`에 전달하여 에러 메시지를 얻을 수 있습니다.
 */
export type WebhookVerificationFailureReason = "MISSING_REQUIRED_HEADERS" | "NO_MATCHING_SIGNATURE" | "INVALID_SIGNATURE" | "TIMESTAMP_TOO_OLD" | "TIMESTAMP_TOO_NEW";
/**
 * 웹훅 요청에 필수적으로 포함되는 헤더들입니다.
 */
export interface WebhookUnbrandedRequiredHeaders {
    "webhook-id": string;
    "webhook-timestamp": string;
    "webhook-signature": string;
}
/**
 * 웹훅 인스턴스에서 사용할 옵션입니다.
 */
export interface WebhookOptions {
    /**
     * 웹훅 시크릿의 포맷입니다.
     *
     * - `"raw"`인 경우, `secret` 파라미터의 값을 그대로 사용합니다.
     * - 지정하지 않을 경우, `secret` 파라미터의 값을 base64 문자열로 간주합니다.
     */
    format?: "raw";
}
/**
 * 웹훅 페이로드를 검증합니다.
 *
 * @param secret 웹훅 시크릿
 * @param payload 웹훅 페이로드
 * @param headers 웹훅 요청 시 포함된 헤더
 * @returns 검증 후 디코딩된 웹훅 페이로드를 반환하는 Promise
 * @throws {@link InvalidInputError} 웹훅 시크릿 혹은 본문이 유효하지 않은 형식일 때 발생합니다.
 * @throws {@link WebhookVerificationError} 웹훅 검증에 실패했을 때 발생합니다.
 */
export declare function verify(secret: string | Uint8Array, payload: string, headers: WebhookUnbrandedRequiredHeaders | Record<string, string | string[] | undefined>): Promise<Webhook>;