npm install @1st-flock/donations-embed @1st-flock/donations-embed-react @1st-flock/donations-embed-node
# or
pnpm add @1st-flock/donations-embed @1st-flock/donations-embed-react @1st-flock/donations-embed-node

NEXT_PUBLIC_FLOCK_PUBLISHABLE_KEY=pk_test_REPLACE_ME
FLOCK_SECRET_KEY=sk_test_REPLACE_ME
FLOCK_WEBHOOK_SECRET=whsec_REPLACE_ME

"use client";

import { FlockDonate } from "@1st-flock/donations-embed-react";

export default function GivePage() {
  return (
    <main>
      <h1>Give to Example Church</h1>
      <p>Thank you for partnering with us.</p>

      <FlockDonate
        publishableKey={process.env.NEXT_PUBLIC_FLOCK_PUBLISHABLE_KEY!}
        mode="inline"
      />
    </main>
  );
}

"use client";

import { FlockDonate } from "@1st-flock/donations-embed-react";

export function DonateForm() {
  return (
    <FlockDonate
      publishableKey={process.env.NEXT_PUBLIC_FLOCK_PUBLISHABLE_KEY!}
      mode="inline"
    />
  );
}

import { DonateForm } from "./donate-form";

export default function GivePage() {
  return (
    <main>
      <h1>Give to Example Church</h1>
      <p>Thank you for partnering with us.</p>
      <DonateForm />
    </main>
  );
}

import dynamic from "next/dynamic";

const FlockDonate = dynamic(
  () => import("@1st-flock/donations-embed-react").then((mod) => mod.FlockDonate),
  { ssr: false },
);

export default function GivePage() {
  return (
    <main>
      <h1>Give to Example Church</h1>
      <FlockDonate
        publishableKey={process.env.NEXT_PUBLIC_FLOCK_PUBLISHABLE_KEY!}
        mode="inline"
      />
    </main>
  );
}

import {
  WebhookFormatError,
  WebhookSignatureError,
  WebhookTimestampError,
  verifyWebhook,
} from "@1st-flock/donations-embed-node";
import { NextResponse } from "next/server";

const SECRET = process.env.FLOCK_WEBHOOK_SECRET!;

export async function POST(request: Request): Promise<Response> {
  const signature = request.headers.get("flock-signature");
  if (!signature) {
    return new NextResponse("missing flock-signature header", { status: 400 });
  }

  // CRITICAL: read the raw body bytes. Do NOT call request.json() — re-serialising
  // the JSON would change the bytes and the signature would not match.
  const body = Buffer.from(await request.arrayBuffer());

  let event: ReturnType<typeof verifyWebhook>;
  try {
    event = verifyWebhook(body, signature, SECRET);
  } catch (err) {
    if (
      err instanceof WebhookSignatureError ||
      err instanceof WebhookTimestampError
    ) {
      // Always 401 for signature failures — never confirm which check failed.
      return new NextResponse("verification failed", { status: 401 });
    }
    if (err instanceof WebhookFormatError) {
      return new NextResponse("malformed delivery", { status: 400 });
    }
    throw err;
  }

  // Dedup by event.id — delivery is at-least-once.
  // (Implement alreadyProcessed/recordEvent against your database.)
  const processed = await alreadyProcessed(event.id);
  if (processed) {
    return new NextResponse(null, { status: 204 });
  }
  await recordEvent(event.id);

  switch (event.type) {
    case "donation.completed":
      await persistReceipt(event.data.object);
      break;
    case "donation.refunded":
      await reverseReceipt(event.data.object);
      break;
    case "recurring.activated":
      await recordNewSubscription(event.data.object);
      break;
    case "key.frozen":
      await alertOnCall(event.data.object);
      break;
    default:
      // Unhandled event types are still valid deliveries — return 204
      // so the platform does not retry.
      break;
  }

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

// Force the route to run dynamically (no caching) so each delivery is verified.
export const dynamic = "force-dynamic";

import {
  WebhookFormatError,
  WebhookSignatureError,
  WebhookTimestampError,
  verifyWebhook,
} from "@1st-flock/donations-embed-node";
import type { NextApiRequest, NextApiResponse } from "next";

const SECRET = process.env.FLOCK_WEBHOOK_SECRET!;

// Disable Next's automatic body parsing — we need the raw bytes.
export const config = {
  api: { bodyParser: false },
};

async function readRawBody(req: NextApiRequest): Promise<Buffer> {
  const chunks: Buffer[] = [];
  for await (const chunk of req) {
    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
  }
  return Buffer.concat(chunks);
}

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
): Promise<void> {
  if (req.method !== "POST") {
    res.status(405).end();
    return;
  }

  const signature = req.headers["flock-signature"];
  if (typeof signature !== "string" || !signature) {
    res.status(400).send("missing flock-signature header");
    return;
  }

  const body = await readRawBody(req);

  let event: ReturnType<typeof verifyWebhook>;
  try {
    event = verifyWebhook(body, signature, SECRET);
  } catch (err) {
    if (
      err instanceof WebhookSignatureError ||
      err instanceof WebhookTimestampError
    ) {
      res.status(401).send("verification failed");
      return;
    }
    if (err instanceof WebhookFormatError) {
      res.status(400).send("malformed delivery");
      return;
    }
    throw err;
  }

  // Dedup + dispatch (same logic as App Router example above).
  // ...

  res.status(204).end();
}