@webhookscheduler/sdk

Thin TypeScript client for Webhook Scheduler: schedule an HTTP request for any future time, watch it deliver with retries and logs, and cancel it before it fires.

• Zero dependencies. Designed for server-side Node.js 18+ runtimes.
• Fully typed: schedule, get, list, cancel, verifySignature.
• The API it wraps is documented and OpenAPI-specced.

Install

npm install @webhookscheduler/sdk

Quickstart

import { WebhookScheduler } from '@webhookscheduler/sdk';

const whs = new WebhookScheduler({ apiKey: process.env.WEBHOOK_SCHEDULER_API_KEY! });

// Schedule a delivery for tomorrow 09:00 UTC
const job = await whs.schedule({
  url: 'https://api.example.com/webhooks/reminder',
  runAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
  body: { userId: 'usr_4821', kind: 'trial_reminder' },
  idempotencyKey: 'trial-reminder-usr_4821',
});

// Inspect it (status, attempts, response codes, latency)
const detail = await whs.get(job.id);

// Cancel it if the user acts first
await whs.cancel(job.id);

// List what's pending
const pending = await whs.list({ status: 'PENDING' });

Get an API key from the dashboard. The free plan needs no credit card.

Next.js example: trial reminder you can cancel

Schedule a reminder when a trial starts, cancel it when the user upgrades. One POST each way, no cron, no queue, no worker.

// app/api/trials/route.ts
import { WebhookScheduler } from '@webhookscheduler/sdk';
import { NextResponse } from 'next/server';

const whs = new WebhookScheduler({ apiKey: process.env.WEBHOOK_SCHEDULER_API_KEY! });

export async function POST(request: Request) {
  const { userId, trialEndsAt } = await request.json();

  // Fire 3 days before the trial ends
  const remindAt = new Date(new Date(trialEndsAt).getTime() - 3 * 24 * 60 * 60 * 1000);

  const job = await whs.schedule({
    url: `${process.env.APP_URL}/api/hooks/trial-reminder`,
    runAt: remindAt,
    body: { userId },
    idempotencyKey: `trial-reminder-${userId}`, // safe to call twice
  });

  // Persist job.id next to the user so you can cancel on upgrade
  return NextResponse.json({ reminderJobId: job.id });
}

// When the user upgrades before the reminder fires:
await whs.cancel(user.reminderJobId);

Verifying deliveries

Every delivery is signed with a Webhook-Signature header (t=<unix>,v1=<hmac-sha256>) using your workspace secret from Settings. Verify against the raw body:

// app/api/hooks/trial-reminder/route.ts
import { verifySignature } from '@webhookscheduler/sdk';
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const rawBody = await request.text();

  const valid = verifySignature({
    payload: rawBody,
    signature: request.headers.get('webhook-signature') ?? '',
    secret: process.env.WEBHOOK_SCHEDULER_SECRET!,
    toleranceSeconds: 300, // reject signatures older than 5 minutes
  });

  if (!valid) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
  }

  const { userId } = JSON.parse(rawBody);
  // ... send the reminder email
  return NextResponse.json({ ok: true });
}

verifySignature uses a timing-safe comparison and never throws on malformed input. It just returns false.

API

| Method | Endpoint | Returns | | --- | --- | --- | | schedule(params) | POST /api/v1/schedule | ScheduledJob | | get(jobId) | GET /api/v1/jobs/{id} | JobDetail (with attempts) | | list(params?) | GET /api/v1/jobs | JobList (paginated) | | cancel(jobId) | POST /api/v1/jobs/{id}/cancel | CanceledJob | | verifySignature(params) | local helper | boolean |

Errors throw WebhookSchedulerError with status, code (e.g. QUOTA_EXCEEDED, UNSAFE_TARGET_URL), and details.

Notes

• Targets must be public HTTPS endpoints; localhost and private networks are rejected (security model).
• Retries use exponential backoff; every attempt is visible in the dashboard and via get().
• Try the API without an account at webhookscheduler.com/try.
• Keep this SDK server-side. It uses your secret API key and imports Node crypto for signature verification.

License

MIT