Guide · Webhooks
Server onlyReceive 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
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{
"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.
1lib/our-impact-webhook.tstypescript
Verify the timestamped HMAC
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);
}2app/api/our-impact/webhook/route.tstypescript
Process each delivery once
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.