SDKs

Official SDKs are available for Node.js, Python, and Go. Each one handles signature verification, JSON parsing, schema validation, and typed email.received events.

Requirements

Node.js >=22

Installation

$npm install @primitivedotdev/sdk

Import

import { confirmedHeaders, handleWebhook, PrimitiveWebhookError } from '@primitivedotdev/sdk';

Webhook Example

Next.js App Router handler.

import {
  confirmedHeaders,
  handleWebhook,
  PrimitiveWebhookError,
} from '@primitivedotdev/sdk';

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

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

    console.log('Event:', event.id);
    console.log('Email from:', event.email.headers.from);
    console.log('Subject:', event.email.headers.subject);

    return Response.json(
      { received: true },
      { headers: confirmedHeaders() }
    );
  } catch (error) {
    if (error instanceof PrimitiveWebhookError) {
      return Response.json({ error: error.code }, { status: 400 });
    }

    throw error;
  }
}

Features

handleWebhook() verifies signatures, parses JSON, and validates email.received.
parseWebhookEvent() keeps unknown future event types intact.
confirmedHeaders() returns the confirmation headers for successful processing.
Raw email helpers decode inline content and verify downloaded bytes.

Good To Know

The SDK accepts Request.headers directly in Fetch and Next.js handlers.

Node-only Extras

@primitivedotdev/sdk/contract builds and signs webhook payloads.
@primitivedotdev/sdk/parser parses raw .eml files and bundles attachments.