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
- Get an API key at https://oakstack.dev/dashboard/api-keys and set it as
OAKSTACK_API_KEY. - 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/...
- Give
endpoint.urlto the sender, in place of your app's URL. In Stripe that's Developers → Webhooks → Add endpoint. - 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 verifyOakstack-Signaturewithendpoint.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:
- one log for every sender, with each attempt's status code and your app's response, for debugging;
- replay after you fix a bug, which senders don't generally offer per event;
- pausing during a risky deploy or maintenance window: events are held and none are lost;
- fast, predictable retries that you can watch, and an inbound URL that stays the same if your app moves.
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:
- Verify
Oakstack-Signaturefirst. It's always fresh, and it proves the request came through your Oakstack endpoint. - Then verify Stripe's signature with a long tolerance. It still proves Stripe created the event.
- 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:
- Deploy the handler above first. It accepts both direct calls from Stripe and calls relayed by Oakstack.
- Create the Oakstack endpoint pointing at that route.
- 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 newwhsec_secret: updateSTRIPE_WEBHOOK_SECRET, deploy, and only then disable the old endpoint. - 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
- The sender POSTs to
https://oakstack.dev/h/<token>. Oakstack stores the event and immediately answers200 {"received": true, "id": "..."}. The sender sees success even if your app is down. - Oakstack forwards it to
forwardUrlright 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...
- Any
2xxfrom your app within 15 seconds marks the eventdelivered. 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 isfailedand 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.