Reference

Webhooks

Receive changes to referrals, orders, rewards and payouts on your backend. Register an HTTPS endpoint in company settings or through the HTTP API. Save the returned signing secret on your server.

Grizzlee delivers each event at least once and retries failures up to eight attempts. The event ID and body stay the same on retries. Deduplicate by event ID. Return a successful status after saving a verified event for processing. See endpoint management for edits and disabling.

Verify deliveries

Grizzlee sends Grizzlee-Event-Id and Grizzlee-Signature. The signature is t=<unix seconds>,v1=<hex HMAC>. Compute HMAC-SHA256 over <timestamp>.<event ID>.<raw body> using your signing secret. Compare signatures in constant time and reject timestamps more than 300 seconds from your clock. A JSON parser must not change the body before verification.

import { verifyWebhook, parseWebhookEvent } from "@grizzlee/sdk/webhooks";

const body = await request.text();
const eventId = request.headers.get("Grizzlee-Event-Id") ?? "";
if (!verifyWebhook({
  body,
  eventId,
  signature: request.headers.get("Grizzlee-Signature") ?? "",
  secret: process.env.GRIZZLEE_WEBHOOK_SECRET!,
})) return new Response("Invalid signature", { status: 401 });

const event = parseWebhookEvent(body);
if (event.id !== eventId) return new Response("Event ID mismatch", { status: 400 });
// Save event once by ID, then process it from your queue.
return new Response(null, { status: 204 });

PHP, Python and Ruby handlers use the same signing algorithm. Use your language's HMAC-SHA256 and constant-time comparison functions on the exact request bytes. The SDK verifier documents its parameters.