API Reference

function createWebhookHandler<TEvent>(
  config: WebhookHandlerConfig<TEvent>
): WebhookHandler<TEvent>;

interface WebhookHandlerConfig<TEvent> {
  /** A provider adapter — stripe(), github(), generic(), etc. */
  provider: ProviderAdapter<TEvent>;

  /** Deduplication store. Omit to disable idempotency entirely (not recommended). */
  idempotency?: IdempotencyStore;

  /** Called once per new, verified event. */
  onEvent: (event: TEvent, ctx: HandlerContext) => Promise<void> | void;

  /**
   * Called instead of the default error response when verification,
   * parsing, or idempotency fails. Return a Response-shaped object
   * to override status/body; omit to use hooksentinel's defaults.
   */
  onError?: (error: HookSentinelError, ctx: HandlerContext) => Promise<ErrorResponse> | ErrorResponse | void;

  /** Max accepted body size in bytes. Default 1_000_000 (1 MB). */
  maxBodyBytes?: number;
}

interface HandlerContext {
  /** The provider-assigned event ID used for deduplication. */
  eventId: string;
  /** The provider name, e.g. "stripe". */
  provider: string;
  /** Raw request headers, lowercased. */
  headers: Record<string, string>;
  /** Unix timestamp (seconds) the request was received. */
  receivedAt: number;
}

interface ErrorResponse {
  status: number;
  body?: unknown;
}

class HookSentinelError extends Error {
  readonly code: HookSentinelErrorCode;
  readonly status: number;
  readonly retryable: boolean;
  readonly provider?: string;
}

type HookSentinelErrorCode =
  | 'invalid_signature'
  | 'missing_signature_header'
  | 'malformed_signature_header'
  | 'timestamp_out_of_tolerance'
  | 'missing_raw_body'
  | 'payload_too_large'
  | 'parse_error'
  | 'duplicate_event'
  | 'idempotency_store_error'
  | 'handler_error'
  | 'provider_verification_error';

function stripe(config: { secret: string; tolerance?: number }): ProviderAdapter<StripeEvent>;
function github(config: { secret: string }): ProviderAdapter<GitHubEvent>;
function shopify(config: { secret: string }): ProviderAdapter<ShopifyEvent>;
function standardWebhooks(config: { secret: string }): ProviderAdapter<StandardWebhookEvent>;
function slack(config: { signingSecret: string }): ProviderAdapter<SlackEvent>;
function discord(config: { publicKey: string }): ProviderAdapter<DiscordInteraction>;
function twilio(config: { authToken: string; url: string }): ProviderAdapter<TwilioEvent>;
function paddle(config: { secret: string }): ProviderAdapter<PaddleEvent>;
function generic(config: {
  secret: string;
  headerName: string;
  algorithm?: 'sha256' | 'sha1' | 'ed25519';
}): ProviderAdapter<unknown>;

interface IdempotencyStore {
  has(eventId: string): Promise<boolean>;
  markProcessed(eventId: string, ttlSeconds?: number): Promise<void>;
  release(eventId: string): Promise<void>;
}

function memoryStore(config?: { maxSize?: number }): IdempotencyStore;

function redisStore(config: {
  url?: string;
  client?: unknown; // an ioredis instance
  ttlSeconds?: number;
}): IdempotencyStore;

function prismaStore(config: {
  client: unknown; // a PrismaClient instance
  model: string;
  ttlSeconds?: number;
  /** When true, hooksentinel checks has() but never calls markProcessed() — see the same-transaction recipe. */
  verifyOnly?: boolean;
}): IdempotencyStore;

// @hooksentinel/core/express
function toExpressHandler(handler: WebhookHandler): (req: Request, res: Response) => Promise<void>;

// @hooksentinel/core/fastify
function toFastifyHandler(handler: WebhookHandler): (req: FastifyRequest, reply: FastifyReply) => Promise<void>;

// @hooksentinel/core/nestjs
class HookSentinelModule {
  static forRoot(config: WebhookHandlerConfig<unknown>): DynamicModule;
  static forRootAsync(config: { imports?: unknown[]; inject?: unknown[]; useFactory: (...args: unknown[]) => WebhookHandlerConfig<unknown> }): DynamicModule;
}
function VerifiedWebhook(): MethodDecorator;
function WebhookEvent(): ParameterDecorator;

// @hooksentinel/core/next
function toRouteHandler(handler: WebhookHandler): (request: Request) => Promise<Response>;

// @hooksentinel/core/hono
function toHonoHandler(handler: WebhookHandler): (c: Context) => Promise<Response>;

// @hooksentinel/core/lambda
function toLambdaHandler(handler: WebhookHandler): APIGatewayProxyHandlerV2;

function createTestSigner(
  provider: 'stripe' | 'github' | 'shopify' | 'standardWebhooks' | 'slack' | 'discord' | 'twilio' | 'paddle' | 'generic',
  config: Record<string, unknown>, // same shape as the matching provider() config
): (
  payload: unknown,
  options?: { timestamp?: number },
) => { body: string; headers: Record<string, string> };