SDK and webhook integration guide.

MEMBERCONSOLE_API_KEY=mc_live_…
MEMBERCONSOLE_WEBHOOK_SECRET=whsec_…

# Never expose either value in browser code, public env variables, logs, or client bundles.

{
  "id": "evt_01JMCEXAMPLE",
  "type": "order.confirmed",
  "api_version": "2026-09-01",
  "created_at": "2026-09-11T03:20:00.000Z",
  "sequence": 1842,
  "resource_version": 7,
  "livemode": true,
  "merchant": {
    "id": "mer_example",
    "slug": "example-store"
  },
  "data": {
    "object": {
      "order_number": "EX-K92L7PQ8",
      "status": "confirmed",
      "payment_status": "paid",
      "fulfillment_status": "unfulfilled"
    }
  },
  "links": {
    "resource": "/v1/merchant/orders/EX-K92L7PQ8"
  }
}

MemberConsole-Event-Id: evt_…
MemberConsole-Timestamp: 1788990000
MemberConsole-Signature: v1=…
MemberConsole-Version: 2026-09-01

signed_payload = timestamp + "." + raw_request_body
expected = HMAC_SHA256(webhook_secret, signed_payload)

import { MemberConsole } from "@memberconsole/server";

const memberconsole = new MemberConsole({
  apiKey: process.env.MEMBERCONSOLE_API_KEY!,
});

export async function POST(request: Request) {
  const rawBody = await request.text();
  const event = await memberconsole.webhooks.verify(
    rawBody,
    request.headers,
    process.env.MEMBERCONSOLE_WEBHOOK_SECRET!,
    { toleranceSeconds: 300 },
  );

  // Insert event.id into durable storage with a UNIQUE/PRIMARY KEY constraint.
  const inserted = await persistWebhookEvent(event);
  if (!inserted) return new Response(null, { status: 204 });

  if (event.type === "order.confirmed") {
    const orderNumber = String(event.data.object.order_number ?? "");
    if (!orderNumber) throw new Error("Missing order_number");

    // Current canonical state wins over assumptions based on delivery order.
    const order = await memberconsole.orders.retrieve(orderNumber);
    await enqueueProvisioningOrFulfillment(order, event.id);
  }

  return new Response(null, { status: 204 });
}

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

function safeHexEqual(a: string, b: string) {
  const aa = Buffer.from(a, "utf8");
  const bb = Buffer.from(b, "utf8");
  return aa.length === bb.length && timingSafeEqual(aa, bb);
}

export function verifyMemberConsoleWebhook(
  rawBody: string,
  headers: Headers,
  secret: string,
) {
  const timestamp = (headers.get("MemberConsole-Timestamp") ?? "").trim();
  const eventId = (headers.get("MemberConsole-Event-Id") ?? "").trim();
  const signatureHeader = headers.get("MemberConsole-Signature") ?? "";

  if (!/^\d{10}$/.test(timestamp)) throw new Error("invalid_timestamp");
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (age > 300) throw new Error("stale_timestamp");

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const signatures = signatureHeader
    .split(",")
    .map((value) => value.trim())
    .filter((value) => value.startsWith("v1="))
    .map((value) => value.slice(3));

  if (!signatures.some((value) => safeHexEqual(value, expected))) throw new Error("invalid_signature");

  const event = JSON.parse(rawBody);
  if (!eventId || event.id !== eventId) throw new Error("event_id_mismatch");
  return event;
}

create table if not exists memberconsole_webhook_events (
  event_id text primary key,
  event_type text not null,
  api_version text not null,
  resource_version bigint null,
  payload jsonb not null,
  received_at timestamptz not null default now(),
  processed_at timestamptz null,
  processing_attempts integer not null default 0,
  last_error text null
);

-- Claim delivery before side effects.
insert into memberconsole_webhook_events (event_id, event_type, api_version, resource_version, payload)
values ($1, $2, $3, $4, $5)
on conflict (event_id) do nothing;

import { MemberConsole } from "@memberconsole/server";

const memberconsole = new MemberConsole({ apiKey: process.env.MEMBERCONSOLE_API_KEY! });

let cursor = await loadMemberConsoleCursor();

for (;;) {
  const page = await memberconsole.events.list({ limit: 100, cursor });
  for (const event of page.data) {
    if (await claimEventId(event.id, event)) await processEvent(event);
  }

  if (!page.next_cursor) break;
  cursor = page.next_cursor; // opaque: store and send back unchanged
  await saveMemberConsoleCursor(cursor);
}

import { MemberConsole } from "@memberconsole/server";

const memberconsole = new MemberConsole({
  apiKey: process.env.MEMBERCONSOLE_API_KEY!,
  // Default base URL: https://api.memberconsole.com/v1/merchant
});

import { MemberConsole } from "@memberconsole/server";

const memberconsole = new MemberConsole({ apiKey: process.env.MEMBERCONSOLE_API_KEY! });

export async function POST(request: Request) {
  const rawBody = await request.text(); // read once, before JSON parsing
  const event = await memberconsole.webhooks.verify(
    rawBody,
    request.headers,
    process.env.MEMBERCONSOLE_WEBHOOK_SECRET!,
  );

  if (await claimEventId(event.id, event)) {
    await queueMemberConsoleEvent(event);
  }

  return new Response(null, { status: 204 });
}

import express from "express";
import { verifyMemberConsoleWebhook } from "@memberconsole/server";

const app = express();

// Important: raw body middleware must run before express.json() for this route.
app.post("/webhooks/memberconsole", express.raw({ type: "application/json" }), async (req, res) => {
  const rawBody = req.body.toString("utf8");
  const event = await verifyMemberConsoleWebhook(
    rawBody,
    req.headers,
    process.env.MEMBERCONSOLE_WEBHOOK_SECRET!,
  );

  const inserted = await persistWebhookEventOnce(event);
  if (inserted) await enqueueMemberConsoleWork(event);
  res.sendStatus(204);
});

app.use(express.json());

import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
import { verifyMemberConsoleWebhook } from "./memberconsole-webhook.ts";

Deno.serve(async (request) => {
  const rawBody = await request.text();
  const event = await verifyMemberConsoleWebhook(
    rawBody,
    request.headers,
    Deno.env.get("MEMBERCONSOLE_WEBHOOK_SECRET")!,
  );

  const supabase = createClient(
    Deno.env.get("SUPABASE_URL")!,
    Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!,
  );

  const { data, error } = await supabase.from("memberconsole_webhook_events")
    .insert({ event_id: event.id, event_type: event.type, payload: event })
    .select("event_id")
    .maybeSingle();

  if (error?.code !== "23505" && error) throw error;
  if (data) await enqueueMemberConsoleWork(event);
  return new Response(null, { status: 204 });
});

export default {
  async fetch(request: Request, env: Env) {
    const rawBody = await request.text();
    const event = await verifyMemberConsoleWebhook(
      rawBody,
      request.headers,
      env.MEMBERCONSOLE_WEBHOOK_SECRET,
    );

    // Durable Object, D1, or another transactional store is preferred for exact deduplication.
    const firstReceipt = await claimEventId(event.id, event, env);
    if (firstReceipt) await env.EVENT_QUEUE.send(event);
    return new Response(null, { status: 204 });
  },
};

Implement MemberConsole as a server-to-server integration. Treat MemberConsole as the canonical commerce source of truth.

Requirements:
1. Create an HTTPS POST webhook endpoint controlled by this application.
2. Read the exact raw request body before JSON parsing.
3. Verify MemberConsole-Timestamp is a 10-digit Unix timestamp and reject requests outside a 300-second replay window.
4. Compute HMAC-SHA256(secret, timestamp + "." + rawBody).
5. Parse MemberConsole-Signature as a comma-separated list and accept the request if any v1= value matches in constant time.
6. Verify MemberConsole-Event-Id exactly equals the signed JSON body event.id.
7. Persist event.id with a UNIQUE or PRIMARY KEY constraint before any provisioning, fulfillment, entitlement, email, or other side effect.
8. Return a 2xx response quickly after durable receipt. Move slow work to a queue/background worker owned by this application.
9. Handle duplicate deliveries as successful no-ops.
10. When ordering matters or an irreversible action depends on current state, retrieve the canonical resource from the MemberConsole Merchant API before acting.
11. Keep MEMBERCONSOLE_API_KEY and MEMBERCONSOLE_WEBHOOK_SECRET server-side only.
12. Never use browser redirects, query strings, localStorage, frontend callbacks, or a payment processor callback as the source of truth for a MemberConsole order.
13. Persist opaque next_cursor values exactly as returned. Never decode or synthesize cursors.
14. For write operations, use stable Idempotency-Key values and If-Match/resource-version controls where applicable.
15. Add tests for valid signature, altered body, stale timestamp, duplicate event, invalid event ID, secret rotation, receiver retry, and reconciliation after downtime.

Prefer @memberconsole/server when it is available to the project. Otherwise implement the verification contract above exactly.