Standard Webhooks Signature Support

Use Standard Webhooks signature support when a receiving system already expects the Standard Webhooks convention (webhook-id / webhook-timestamp / webhook-signature headers, whsec_-prefixed secret) instead of Primitive's own scheme. This is the alternative path; the default is the Primitive-Signature HMAC header described in Webhook Signature Verification, and primitive.receive(...) / handleWebhook(...) verify that default automatically for you.

Reach for this page only if you're integrating with tooling built around Standard Webhooks, or you need to sign outbound deliveries in that format yourself. For the general webhook contract (event catalog, X-Webhook-Event header, forward compatibility), see Webhook Events Overview.

Verify a Standard Webhooks delivery#

verifyStandardWebhooksSignature, exported from @primitivedotdev/sdk/webhook, checks a delivery's webhook-id, webhook-timestamp, and webhook-signature headers against your secret.

1. 1

   Import the helper#

   import { verifyStandardWebhooksSignature } from "@primitivedotdev/sdk/webhook";
   

2. 2

   Read the raw body and the three headers#

   The signature is computed over the exact request bytes, so read the raw body before any JSON parsing, the same requirement as the Primitive-Signature scheme.

   const rawBody = await request.text(); // exact bytes, not a re-serialized parse
   const msgId = request.headers.get("webhook-id")!;
   const timestamp = request.headers.get("webhook-timestamp")!;
   const signatureHeader = request.headers.get("webhook-signature")!;
   

3. 3

   Verify against your whsec_ secret#

   verifyStandardWebhooksSignature({
     rawBody,
     msgId,
     timestamp,
     signatureHeader,
     secret: process.env.PRIMITIVE_WEBHOOK_SECRET!, // whsec_...
   });
   

   Expected result: the call returns without throwing when the signature is valid. Any mismatch, expired timestamp, or malformed header throws WebhookVerificationError.

import { verifyStandardWebhooksSignature, WebhookVerificationError } from "@primitivedotdev/sdk/webhook";

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

  try {
    verifyStandardWebhooksSignature({
      rawBody,
      msgId: req.headers.get("webhook-id")!,
      timestamp: req.headers.get("webhook-timestamp")!,
      signatureHeader: req.headers.get("webhook-signature")!,
      secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,
    });
  } catch (err) {
    if (err instanceof WebhookVerificationError) {
      return new Response(err.code, { status: 400 });
    }
    throw err;
  }

  return Response.json({ ok: true });
}

Secret format#

A Standard Webhooks secret is base64-encoded and may carry a whsec_ prefix. verifyStandardWebhooksSignature accepts it with or without the prefix and does the base64 decode for you, so pass it exactly as issued and do not decode it yourself. A secret that isn't base64 after the prefix is stripped throws WebhookVerificationError with code MISSING_SECRET. This differs from the default Primitive-Signature scheme, whose secret (from GET /account/webhook-secret) is used verbatim as a UTF-8 string and must never be base64-decoded.

Sign a payload yourself#

If you need to emit a Standard Webhooks-formatted signature (for example, replaying a fixture in tests), use signStandardWebhooksPayload:

import { signStandardWebhooksPayload } from "@primitivedotdev/sdk/webhook";

const { signature, msgId, timestamp } = signStandardWebhooksPayload(
  rawBodyString,
  process.env.PRIMITIVE_WEBHOOK_SECRET!, // whsec_...
  "msg_test_123", // your own message id
);

Send signature as the webhook-signature header, msgId as webhook-id, and timestamp as webhook-timestamp on the outbound request.

Choosing between the two schemes#

Both schemes verify the exact raw request bytes and default to a 300-second replay window.

Next steps#