Webhooks

curl -X POST http://localhost:6767/apps/$APP_ID/webhooks \
  -H "Authorization: Bearer $OFFER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://blog.example.com/api/webhooks",
    "events": ["checkout.completed", "cancel_flow.cancelled"]
  }'

{
  "id": "whk_QwErTyNiOpAsDfGh",
  "app_id": "app_AbCdEf",
  "url": "https://blog.example.com/api/webhooks",
  "description": null,
  "events": ["checkout.completed", "cancel_flow.cancelled"],
  "enabled": true,
  "source": "custom",
  "secret": "whsec_…",
  "disabled_reason": null,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z",
  "stats": { "total": 0, "succeeded": 0, "failed": 0, "pending": 0, "last_delivery_at": null, "last_status": null, "last_response_status": null }
}

POST /api/webhooks HTTP/1.1
Content-Type: application/json
User-Agent: OfferSDK-Webhooks/1.0
webhook-id: evt_kTnBwQzXyPcRfLmHsDaGqEoJ
webhook-timestamp: 1790856000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "id": "evt_kTnBwQzXyPcRfLmHsDaGqEoJ",
  "type": "account.plan_changed",
  "created_at": "2026-10-01T12:00:00.000Z",
  "app_id": "app_AbCdEf",
  "data": {
    "object": { "id": "user_42", "app_id": "app_AbCdEf", "name": "Ada", "plan": "pro", "incentive": null, "created_at": "2026-09-01T09:30:00.000Z" },
    "previous": { "plan": "free" }
  }
}

// app/api/webhooks/route.ts
import { Webhook, WebhookVerificationError } from "standardwebhooks";

const SECRET = process.env.OFFER_WEBHOOK_SECRET!; // "whsec_…"

export async function POST(req: Request) {
  const body = await req.text(); // the raw body, before any JSON parsing
  const headers = Object.fromEntries(req.headers);

  let event: { id: string; type: string; data: Record<string, unknown> };
  try {
    event = new Webhook(SECRET.slice("whsec_".length)).verify(body, headers) as typeof event;
  } catch (err) {
    if (err instanceof WebhookVerificationError) return Response.json({ error: err.message }, { status: 401 });
    throw err;
  }

  // Retries reuse the event id, so skip ids you've already handled.
  if (await alreadyHandled(event.id)) return Response.json({ received: true });

  switch (event.type) {
    case "checkout.completed":
      // link data.account.id to your user, send a receipt…
      break;
    case "cancel_flow.cancelled":
      // stop billing you run outside PayPal…
      break;
  }
  return Response.json({ received: true });
}

import { createHmac, timingSafeEqual } from "node:crypto";

/** Standard Webhooks verification without a library. */
export function verifyOfferWebhook(secret: string, headers: Headers, body: string, toleranceSeconds = 300): boolean {
  const id = headers.get("webhook-id");
  const timestamp = headers.get("webhook-timestamp");
  const signatures = headers.get("webhook-signature");
  if (!id || !timestamp || !signatures) return false;

  // Reject old requests, so a captured one can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = Buffer.from(createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64"));

  // The header can hold several space-separated "v1,<signature>" entries.
  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    const actual = Buffer.from(signature ?? "");
    return version === "v1" && actual.length === expected.length && timingSafeEqual(actual, expected);
  });
}

{
  "id": "whd_pLmKjHgFdSaQwErTyIoPZxCb",
  "endpoint_id": "whk_QwErTyNiOpAsDfGh",
  "event_id": "evt_kTnBwQzXyPcRfLmHsDaGqEoJ",
  "event_type": "account.plan_changed",
  "status": "pending",
  "attempts": 2,
  "next_attempt_at": "2026-10-01T12:06:00.000Z",
  "last_attempt_at": "2026-10-01T12:01:00.000Z",
  "response_status": 500,
  "response_body": "Internal Server Error",
  "error": "HTTP 500",
  "duration_ms": 182,
  "test": false,
  "created_at": "2026-10-01T12:00:00.000Z",
  "payload": { "id": "evt_kTnBwQzXyPcRfLmHsDaGqEoJ", "type": "account.plan_changed", "…": "…" }
}

curl -X POST http://localhost:6767/apps/$APP_ID/webhooks/$WEBHOOK_ID/test \
  -H "Authorization: Bearer $OFFER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "checkout.completed" }'

{
  "object": {
    "account_id": "user_42",
    "entitlement_id": "posts",
    "entitlement_name": "Posts",
    "usage": 40,
    "max": 50,
    "left": 10,
    "percent": 80
  }
}