Oakhook: webhook relay

A permanent inbound URL for webhooks from Stripe, GitHub, Shopify, or any other service. Oakstack accepts and stores every event the moment it arrives, then forwards it to your app with the original headers and body. It keeps retrying for about 11 hours while your app is down, and you can replay any event.

Use it so that a deploy, an outage, or a bug in your webhook handler never loses an event.

Quick start

  1. Get an API key at https://oakstack.dev/dashboard/api-keys and set it as OAKSTACK_API_KEY.
  2. Create an endpoint that forwards to your app's existing webhook route:
import { Oakstack } from "oakstack";
const oakstack = new Oakstack();

const endpoint = await oakstack.hook.endpoints.create({
  name: "Stripe",
  forwardUrl: "https://yourapp.com/api/webhooks/stripe",
});
console.log(endpoint.url); // https://oakstack.dev/h/...
  1. Give endpoint.url to the sender, in place of your app's URL. In Stripe that's Developers → Webhooks → Add endpoint.
  2. Keep verifying the sender's own signature in your app, exactly as before. Oakstack forwards the original headers (for example Stripe-Signature) and the exact body bytes, so it still passes. Optionally also verify Oakstack-Signature with endpoint.signingSecret (see Verifying requests).

When something goes wrong:

const failed = await oakstack.hook.endpoints.events(endpoint.id, { status: "failed" });
const detail = await oakstack.hook.events.get(failed[0].id); // headers, body, every attempt
// ...fix your handler, then:
await oakstack.hook.events.replay(failed[0].id);

Agents can do the same with the MCP tools hook_create_endpoint, hook_list_events, hook_get_event, and hook_replay_event.

Why use it if the sender already retries?

Stripe retries failed webhooks for about 3 days, and many senders do something similar. Oakhook adds:

Using Oakhook with Stripe (read this)

Stripe's signature check (constructEvent) rejects signatures more than 5 minutes old by default. Oakhook forwards Stripe's original Stripe-Signature header unchanged, timestamp included. So any event delivered later than that is rejected by the default check: an automatic retry after the first few attempts, an event held while paused, or a replay. That would lose exactly the events Oakhook is there to save.

Use this pattern instead:

  1. Verify Oakstack-Signature first. It's always fresh, and it proves the request came through your Oakstack endpoint.
  2. Then verify Stripe's signature with a long tolerance. It still proves Stripe created the event.
  3. Skip events you've already processed (store event.id). Delivery is at least once, and a long tolerance means an old event could be sent again.
// app/api/webhooks/stripe/route.ts
import Stripe from "stripe";
import { verifySignature } from "oakstack";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const RELAYED_TOLERANCE = 60 * 60 * 24 * 30; // 30 days: covers retries, holds while paused, and replays

export async function POST(req: Request) {
  const raw = await req.text(); // read the raw body once, before any parsing
  const viaOakstack = req.headers.has("oakstack-signature");
  if (viaOakstack) {
    const ok = await verifySignature(
      process.env.OAKSTACK_WEBHOOK_SECRET!,
      req.headers.get("oakstack-signature"),
      raw,
    );
    if (!ok) return new Response("bad Oakstack signature", { status: 401 });
  }

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      raw,
      req.headers.get("stripe-signature")!,
      process.env.STRIPE_WEBHOOK_SECRET!,
      viaOakstack ? RELAYED_TOLERANCE : undefined, // direct calls keep Stripe's 5-minute default
    );
  } catch {
    return new Response("bad Stripe signature", { status: 400 });
  }

  if (await alreadyProcessed(event.id)) return Response.json({ received: true, duplicate: true });
  // ... handle the event. Throw or return 5xx on failure so Oakstack retries.
  await markProcessed(event.id);
  return Response.json({ received: true });
}

Switching Stripe over without missing events:

  1. Deploy the handler above first. It accepts both direct calls from Stripe and calls relayed by Oakstack.
  2. Create the Oakstack endpoint pointing at that route.
  3. In Stripe (Developers → Webhooks), edit your existing endpoint's URL to the Oakstack inbound URL. That keeps the same whsec_ signing secret. If you add a new Stripe endpoint instead, Stripe gives it a new whsec_ secret: update STRIPE_WEBHOOK_SECRET, deploy, and only then disable the old endpoint.
  4. Send a test webhook from Stripe and check the Oakstack event log for delivered.

The same applies to other senders that put timestamps in their signatures (for example Clerk/Svix and Slack): verify Oakstack's signature first, then use the sender's library with a longer tolerance. GitHub's signature has no timestamp, so its check needs no changes.

What happens to an event

  1. The sender POSTs to https://oakstack.dev/h/<token>. Oakstack stores the event and immediately answers 200 {"received": true, "id": "..."}. The sender sees success even if your app is down.
  2. Oakstack forwards it to forwardUrl right away, with the same method, body, and headers, plus:
Oakstack-Event-Id: 2b7e...        the same across retries; use it to skip duplicates
Oakstack-Endpoint-Id: 9c1d...
Oakstack-Received-At: 2026-10-05T14:02:11.000Z
Oakstack-Attempt: 1               1-8
Oakstack-Signature: t=1791208931,v1=a41f...
  1. Any 2xx from your app within 15 seconds marks the event delivered. Anything else is a failure, and it's retried after about 30 seconds, then 2 minutes, 10 minutes, 30 minutes, 1 hour, 3 hours, and 6 hours: 8 attempts over about 11 hours. After that the event is failed and stays in the log, where you can replay it.

Delivery is at least once and order isn't guaranteed, so make your handler safe to run twice. Oakstack-Event-Id, or the sender's own event id, works as a dedupe key.

Redirects aren't followed. Forward to the final URL.

Pausing

Pausing an endpoint pauses forwarding only. Events keep arriving and are stored, and when you resume, they are all forwarded. Use it during a risky deploy or while you fix a broken handler.

Replay

POST /api/v1/hook/events/:id/replay (or the Replay button in the dashboard) forwards a copy of the event again, with replayOf pointing at the original. Each replay counts as one event toward your monthly limit.

Verifying requests

import { verifySignature } from "oakstack";

export async function POST(req: Request) {
  const raw = new Uint8Array(await req.arrayBuffer()); // read once, use for every check
  if (
    !(await verifySignature(
      process.env.OAKSTACK_WEBHOOK_SECRET!,
      req.headers.get("oakstack-signature"),
      raw,
    ))
  ) {
    return new Response("bad signature", { status: 401 });
  }
  // Then verify the sender's own signature on the same raw body, as usual, e.g.
  // stripe.webhooks.constructEvent(Buffer.from(raw), req.headers.get("stripe-signature")!, STRIPE_WEBHOOK_SECRET)
  return Response.json({ ok: true });
}

A replayed event gets a fresh Oakstack-Signature, but the sender's original signature keeps its old timestamp. A strict sender check (Stripe's default tolerance is 5 minutes) may reject a replay of an old event. The scheme, and versions without the SDK, are in signatures.

API reference

SDK methods: oakstack.hook.endpoints.create, .list, .get, .update, .delete, .events; oakstack.hook.events.get, .replay.

All REST endpoints take Authorization: Bearer <API key>. Write endpoints accept Idempotency-Key.

Method Path What it does
POST /api/v1/hook/endpoints Create an endpoint: { "name", "forwardUrl" }. Returns 201.
GET /api/v1/hook/endpoints List endpoints.
GET /api/v1/hook/endpoints/:id Get one endpoint.
PATCH /api/v1/hook/endpoints/:id Change name or forwardUrl, or set status to paused or active.
DELETE /api/v1/hook/endpoints/:id Delete an endpoint and its events. Its inbound URL then answers 404.
GET /api/v1/hook/endpoints/:id/events Recent events, newest first. ?status=failed, ?limit= up to 100.
GET /api/v1/hook/events/:id One event with headers, body, and every delivery attempt.
POST /api/v1/hook/events/:id/replay Forward the event again. Returns 202 with the new event.

Endpoint fields: id, name, url (inbound), forwardUrl, status, pausedReason, lastEventAt, signingSecret, createdAt, updatedAt.

Event fields: id, endpointId, replayOf, receivedAt, method, sizeBytes, sourceIp, status (pending, delivering, delivered, or failed), attempt, maxAttempts, nextAttemptAt, lastResponseStatus, lastError, and deliveredAt. A single event also has headers, body, bodyEncoding (utf8, or base64 for binary bodies), and attempts.

The inbound URL

POST, PUT, or PATCH to /h/<token>. No API key is needed: the unguessable token is the address, so treat it like a secret. If one leaks, create a new endpoint and delete the old one.

Status When
200 Stored. Body: {"received": true, "id": "..."}
404 Unknown or deleted endpoint
405 Wrong method (for example GET)
413 Body over 1 MB
429 Your workspace reached its monthly event limit. Senders retry later.
403 Your workspace is paused or suspended

Limits

Plan Events per month
Free 1,000
Builder 50,000
Studio 250,000

Counted when an event arrives, and again for each replay. Event logs are kept for 7 days (30 on Studio). Bodies up to 1 MB.

Plan Endpoints
Free 5
Builder 50
Studio 200

Each inbound URL accepts up to 600 events a minute. Beyond that, senders get a 429 with Retry-After and retry, and nothing extra is counted. Events held on a paused endpoint expire (marked failed) after 30 days.