Webhooks Guide

{
  "id": "evt_6ad99e8d88a7b7fc68abd161",
  "type": "subscription.plan_changed",
  "apiVersion": "2026-11-01",
  "createdAt": "2026-10-22T05:26:37.250Z",
  "clientId": "3pm_099c0cb053a73317",
  "tenantId": "6a2fd9d87ea2db29cba8cbdd",
  "actor": { "type": "admin", "id": "6a16909b9e3f70adecf42b30" },
  "data": {
    "object":   { "...": "the thing as it is now" },
    "previous": { "...": "what it was before (only on some events)" }
  }
}

import crypto from "crypto";

const TOLERANCE_SECONDS = 300;

export function verify3pmWebhook(rawBody: string, header: string | null, secret: string): boolean {
  if (!header) return false;
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`, "utf8").digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(parts.v1, "utf8");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;

  return Math.abs(Date.now() / 1000 - t) <= TOLERANCE_SECONDS;
}

import express from "express";
import { verify3pmWebhook } from "./verify-3pm-webhook";

const router = express.Router();

// express.raw — the signature is over the exact bytes we were sent.
router.post("/webhooks/3pm", express.raw({ type: "application/json" }), async (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verify3pmWebhook(raw, req.header("3PM-Signature") ?? null, process.env.THREEPM_WEBHOOK_SECRET!)) {
    return res.status(400).send("Invalid signature");
  }
  const event = JSON.parse(raw);

  // Same event can arrive twice: remember the ids you have handled.
  if (await alreadyHandled(event.id)) return res.sendStatus(200);

  await saveForProcessing(event); // store it (quick), handle it in the background
  res.sendStatus(200);            // answer within 10 seconds
});

export default router;

import { verify3pmWebhook } from "@/lib/verify-3pm-webhook";

export async function POST(request: Request) {
  const raw = await request.text(); // raw body — don't use request.json() first
  if (!verify3pmWebhook(raw, request.headers.get("3PM-Signature"), process.env.THREEPM_WEBHOOK_SECRET!)) {
    return new Response("Invalid signature", { status: 400 });
  }
  const event = JSON.parse(raw);
  // …de-duplicate by event.id, save, then:
  return new Response(null, { status: 200 });
}

{
  "object": {
    "tenantId": "6a2fd9d87ea2db29cba8cbdd",
    "clientId": "3pm_099c0cb053a73317",
    "status": "active",
    "planId": "pro",
    "planName": "Pro",
    "effectivePlanId": "pro",
    "effectivePlanName": "Pro",
    "onTrial": false,
    "trialPlanId": null,
    "trialEndsAt": null,
    "seats": 2,
    "billing": "monthly",
    "bundle": null,
    "subscribedAt": "2026-10-22T05:26:09.071Z",
    "cancelledAt": null
  },
  "previous": {
    "status": "active",
    "planId": "free",
    "effectivePlanId": "pro",
    "effectivePlanName": "Pro",
    "trialEndsAt": "2026-11-01T05:26:34.692Z"
  }
}

{
  "object": {
    "tenantId": "6a2fd9d87ea2db29cba8cbdd",
    "clientId": "3pm_099c0cb053a73317",
    "userId": "6a2fd91c7ea2db29cba8cbd4",
    "via": "app"
  }
}

{
  "object": {
    "tenantId": "6a2fd9d87ea2db29cba8cbdd",
    "clientId": "3pm_099c0cb053a73317",
    "amount": 1500,
    "bucket": "purchased",
    "balance": 101500,
    "description": "Top up pack × 3",
    "packId": "topup",
    "packName": "Top up",
    "quantity": 3,
    "orderId": "876a1e8e-b326-4787-b32e-ec41b1b3ba57"
  }
}

{
  "object": {
    "tenantId": "6a2fd9d87ea2db29cba8cbdd",
    "clientId": "3pm_099c0cb053a73317",
    "amount": 100,
    "bucket": "bonus",
    "balance": 101600,
    "description": "Welcome bonus",
    "idempotencyKey": "my-app-grant-0001"
  }
}

try:   1    2     3     4     5    6    7    8     9     10    11    12
at:   now  1m    5m    15m   1h   3h   6h   12h   24h   36h   48h   72h

{
  "object": {
    "message": "This is a test event from 3PM Auth. If you can read it, your endpoint works.",
    "endpointId": "whk_6ad8aaf39f0974ed9a0d9780"
  }
}