Documentation

Get started monitoring your webhooks in under 60 seconds.

Installation

Install the Outworx Hooks SDK using your preferred package manager.

npm

npm install outworx-hooks

yarn

yarn add outworx-hooks

pnpm

pnpm add outworx-hooks

Quick Start

Wrap your existing webhook handler with the Outworx monitoring layer. Choose your framework below.

// app/api/webhooks/stripe/route.ts
import { init } from 'outworx-hooks';
import { withWebhookMonitoring } from 'outworx-hooks/nextjs';

init({ apiKey: process.env.OUTWORX_API_KEY! });

export const POST = withWebhookMonitoring(
  { provider: 'stripe' },
  async (req) => {
    const body = await req.json();
    // handle webhook event
    return Response.json({ received: true });
  }
);

Configuration

Configure the SDK with your API key and optional settings.

import { init } from 'outworx-hooks';

init({
  // Required: your Outworx API key
  apiKey: process.env.OUTWORX_API_KEY!,

  // Optional: custom endpoint (for enterprise)
  endpoint: 'https://ingest.outworx.io',

  // Optional: enable debug logging
  debug: false,

  // Optional: capture request/response bodies
  capturePayloads: false,

  // Optional: custom headers to redact
  redactHeaders: ['authorization', 'x-api-key', 'cookie'],

  // Optional: timeout for telemetry sends (ms)
  timeout: 5000,
});

Track Options

Customize tracking per handler with these options.

withWebhookMonitoring({
  // Required: identify the webhook provider
  provider: 'stripe',

  // Optional: custom event name
  eventName: 'payment.received',

  // Optional: override global payload capture
  capturePayloads: true,

  // Optional: custom metadata attached to events
  metadata: {
    environment: 'production',
    service: 'billing',
  },

  // Optional: custom tags for filtering
  tags: ['payments', 'critical'],
}, handler);

Option	Type	Default	Description
provider	string	required	Webhook provider name (stripe, shopify, github, etc.)
eventName	string	auto	Custom event name. Auto-detected from provider headers if not set.
capturePayloads	boolean	false	Capture request and response bodies.
metadata	object	{}	Custom key-value pairs attached to every event.
tags	string[]	[]	Tags for filtering and grouping events in the dashboard.

Environment Variables

The SDK supports configuration via environment variables as an alternative to the init function.

.env

# Required
OUTWORX_API_KEY=ohk_your_api_key_here

# Optional
OUTWORX_ENDPOINT=https://ingest.outworx.io
OUTWORX_DEBUG=false
OUTWORX_CAPTURE_PAYLOADS=false
OUTWORX_TIMEOUT=5000

When using environment variables, you can initialize without arguments:

import { init } from 'outworx-hooks';

// Reads from OUTWORX_API_KEY automatically
init();