Guide · Webhooks

Server only

Receive signed activity and entitlement changes.

Webhooks let your backend react asynchronously when verified supporter activity arrives or an entitlement changes state.

Create an endpoint

In the developer project’s API & Webhooks tab, add a public HTTPS URL. Copy the signing secret immediately; it is shown only when the endpoint is created.

Request format

Webhook headers
POST /api/our-impact/webhook HTTP/1.1
Content-Type: application/json
Our-Impact-Event: entitlement.granted
Our-Impact-Delivery: 6ff3c38e-...
Our-Impact-Signature: t=1794362400,v1=HEX_HMAC
Example payload
{
  "id": "019a6f04-...",
  "type": "entitlement.granted",
  "created_at": "2026-11-11T08:00:00.000Z",
  "data": {
    "external_user_id": "storefront:user_123",
    "entitlement": "community_champion",
    "state": "active",
    "qualifying_count": 3,
    "valid_until": null
  }
}

Verify before parsing

The signature covers the exact raw request body. Do not parse and re-stringify the body before verification.

1

Verify the timestamped HMAC

lib/our-impact-webhook.ts
import { createHmac, timingSafeEqual } from "node:crypto";

function verifyOurImpactWebhook(rawBody: string, signature: string, secret: string) {
  const parts = Object.fromEntries(
    signature.split(",").map((part) => part.split("=", 2)),
  );
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(String(timestamp) + "." + rawBody)
    .digest("hex");
  const received = parts.v1 ?? "";
  const left = Buffer.from(expected);
  const right = Buffer.from(received);

  return left.length === right.length && timingSafeEqual(left, right);
}
2

Process each delivery once

app/api/our-impact/webhook/route.ts
export async function POST(request: Request) {
  const rawBody = await request.text();
  const signature = request.headers.get("our-impact-signature") ?? "";

  if (!verifyOurImpactWebhook(
    rawBody,
    signature,
    process.env.OUR_IMPACT_WEBHOOK_SECRET!,
  )) {
    return Response.json({ error: "invalid_signature" }, { status: 401 });
  }

  const deliveryId = request.headers.get("our-impact-delivery");
  const event = JSON.parse(rawBody);
  await processOnce(deliveryId, event);

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

Events and delivery behavior

donation.completedA verified donation event entered the developer project.
entitlement.grantedA supporter newly qualified for an entitlement.
entitlement.revokedA supporter no longer qualifies or the entitlement was disabled.