Handling Payment and Interaction Webhook Events

Use handleWebhookEvent, the verify-then-classify entry point in @primitivedotdev/sdk/webhook, to handle email.*, payment.*, and interaction.x402.* deliveries from a single endpoint. Reach for it when the same webhook URL you registered for inbound mail also receives x402 settlement and interaction events.

Why the header matters#

The X-Webhook-Event header is the only discriminator present on every webhook family, so it is what the SDK keys on. Primitive names every delivery in that header, not in the body. The stored body is sent verbatim with no shared envelope, so its shape differs by family:

Because interaction.* bodies carry no discriminator at all, the header is the only reliable signal across every family. handleWebhookEvent reads it for you and overlays a canonical event field onto the parsed result so your code always branches on one field, regardless of family.

Verify and classify in one call#

handleWebhookEvent verifies the Primitive-Signature HMAC over the raw body first (this step is identical to webhook signature verification and independent of the event family), then parses the JSON and classifies it on the X-Webhook-Event header.

1. 1

   Import the handler and type guards#

   import {
     handleWebhookEvent,
     isPaymentSettledEvent,
     isInteractionX402Event,
   } from "@primitivedotdev/sdk/webhook";
   

2. 2

   Call handleWebhookEvent with the raw body, headers, and secret#

   const event = handleWebhookEvent({
     body: rawBodyString,
     headers: req.headers,
     secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,
   });
   

   body must be the exact request bytes before any JSON parsing. headers accepts a plain object (Express req.headers) or a Fetch API Headers instance. secret is your account's webhook secret, returned by GET /account/webhook-secret.

3. 3

   Branch on the typed event#

   if (isPaymentSettledEvent(event)) {
     // typed PaymentSettledEvent: flat fields, amount in token base units
     console.log("settled", event.challenge_id, event.amount, event.settle_tx);
   } else if (isInteractionX402Event(event)) {
     // typed interaction.x402.* event (challenge/payment/settled/...)
     console.log(event.event, event.interaction);
   } else if (event.event === "email.received") {
     // fully typed EmailReceivedEvent — see the email-model docs
     console.log(event.email.headers.subject);
   } else {
     // UnknownEvent: a future event type this SDK version doesn't know about yet
     console.log("unhandled event:", event.event);
   }
   

Expected result: for a known event type, event is a typed value matching that family's shape; for anything the current SDK doesn't recognize, event is an UnknownEvent with event and the raw payload preserved, the call never throws for an unrecognized (but well-signed) event type.

The event catalog#

The SDK classifies 19 header values across four families, exported as the WEBHOOK_EVENT_TYPES array and the WebhookEventType union:

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

Only email.received is validated against the canonical JSON Schema and returned as a fully typed EmailReceivedEvent. Every other known type is returned as its body plus a canonical event field overlaid from the header. See Webhook Events Overview for the cross-SDK contract and forward-compatibility guarantees this catalog is part of.

Typed shapes for payment and interaction events#

PaymentEvent (and its narrower PaymentSettledEvent / PaymentFailedEvent variants) carries flat fields, no nested payment object:

import type { PaymentEvent, PaymentSettledEvent, PaymentFailedEvent } from "@primitivedotdev/sdk/webhook";

• challenge_id, the x402 payment challenge this event settles or fails
• amount, token base units (USDC has 6 decimals, so "10000" is 0.01 USDC)
• settle_tx, present on payment.settled, the on-chain settlement transaction hash
• failure_reason, present on payment.failed

InteractionX402Event wraps the raw { interaction: {...} } body plus the canonical event name from the header:

import type { InteractionX402Event } from "@primitivedotdev/sdk/webhook";

Use isPaymentEvent, isPaymentSettledEvent, isPaymentFailedEvent, and isInteractionX402Event as type guards to narrow WebhookEvent without manually checking event strings.

handleWebhookEvent vs. handleWebhook#

handleWebhook remains hard-typed to email.received for backward compatibility, it throws on anything else. handleWebhookEvent is the superset: same signature verification, but it returns the full WebhookEvent union instead of throwing on a payment or interaction delivery.

Next steps#