Receive webhooks

Webhooks notify your server when loyalty activity changes. Use them for fast updates, then run periodic reconciliation so one delayed delivery cannot leave systems permanently out of sync.

Create an endpoint

Create webhook configuration with a narrowly scoped live key or in the dashboard. The plaintext signing secret is returned once.

curl --request POST "$PERKSTAR_API_URL/webhooks" \
  --header "Authorization: Bearer $PERKSTAR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: webhook-primary-v1" \
  --data '{
    "url": "https://integration.example.com/webhooks/perkstar",
    "events": ["transaction.created", "customer.enrolled"]
  }'

Store the returned secret in the receiving service’s secret manager before the response is discarded. Common event names include:

customer.enrolled, customer.unenrolled, customer.anonymized
transaction.created, reward.redeemed, coupon.redeemed, tier.changed
membership.purchased, membership.renewed, membership.cancelled
booking.created, booking.attended, booking.no_show, booking.cancelled
webhook.test

Verify before parsing

Perkstar sends a Stripe-style signature:

X-Perkstar-Signature: t=1785312000,v1=<hex-hmac-sha256>

The signed value is <timestamp>.<raw request body>. Verify the raw bytes and a five-minute timestamp tolerance before trusting or parsing the JSON.

import { verifyWebhookSignature } from "@perkstar/api-client/webhooks";

const rawBody = await request.text();
const event = verifyWebhookSignature({
  payload: rawBody,
  signature: request.headers.get("x-perkstar-signature") ?? "",
  secret: process.env.PERKSTAR_WEBHOOK_SECRET!,
});

await processOnce(event.id, event);
return new Response(null, { status: 200 });

Reading JSON first and serialising it again changes the signed bytes. Capture the raw body before any framework body parser runs.

Processing rules

Verify the signature and timestamp.
Deduplicate by event ID in your database.
Persist or enqueue the event before returning 2xx.
Process asynchronously when work could exceed a few seconds.
Make handlers safe when events arrive twice or out of order.
Branch test traffic using testMode: true.

Return a non-2xx status only when a retry may help. Validation failures should be recorded for operator review rather than retried forever.

Reconciliation

At least daily, compare the external system with recent Perkstar transactions or customers. Webhooks provide speed, while reconciliation catches exhausted retries, downtime, and deployment mistakes.

Get started

Core concepts

Integration recipes

Ship safely

Create an endpoint

Verify before parsing

Processing rules

Reconciliation

​Create an endpoint

​Verify before parsing

​Processing rules

​Reconciliation

Create an endpoint

Verify before parsing

Processing rules

Reconciliation