Overview

Webhooks allow you to receive real-time HTTP notifications when events happen in your LoyalPro account. Instead of polling our API, webhooks push data to your server as soon as events occur.

Real-time

Instant notifications when events occur

Reliable

Automatic retries with exponential backoff

Secure

Signed payloads for verification

Setting Up Webhooks

To receive webhook notifications, you need to configure an endpoint URL in your LoyalPro dashboard.

Go to your LoyalPro Dashboard → Developers → Webhooks

Click 'Add Endpoint' and enter your webhook URL

Select the events you want to receive

Copy your webhook signing secret for verification

Example Webhook Endpoint (Next.js API Route)

// app/api/webhooks/loyalpro/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const event = await request.json();
  
  switch (event.type) {
    case 'points.earned':
      console.log('Points earned:', event.data);
      // Handle points earned event
      break;
    case 'customer.created':
      console.log('New customer:', event.data);
      // Handle new customer event
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }
  
  return NextResponse.json({ received: true });
}

Webhook Events

LoyalPro sends webhooks for various events. Here are all the available event types:

Customer Events

customer.created

Triggered when a new customer is enrolled

customer.updated

Triggered when customer details are modified

customer.deleted

Triggered when a customer is removed

customer.tier_changed

Triggered when a customer's tier changes

Points Events

points.earned

Triggered when points are awarded to a customer

points.redeemed

Triggered when points are redeemed

points.expired

Triggered when points expire

points.adjusted

Triggered when points are manually adjusted

Transaction Events

transaction.completed

Triggered when a purchase is recorded

transaction.refunded

Triggered when a transaction is refunded

Alert Events

fraud.detected

Triggered when suspicious activity is detected

churn.risk

Triggered when a customer is flagged as at-risk

Security & Verification

LoyalPro signs all webhook payloads with a secret key. Always verify the signature to ensure the webhook came from LoyalPro.

Important Security Note

Never process webhooks without verifying the signature first. This protects you from malicious requests.

Signature Verification (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler:
const signature = req.headers['x-loyalpro-signature'];
const isValid = verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET);

if (!isValid) {
  return res.status(401).json({ error: 'Invalid signature' });
}

Best Practices

Respond quickly

Return a 2xx response within 30 seconds. Process heavy tasks asynchronously using a job queue.

Handle duplicates

Use the event ID to detect and handle duplicate deliveries. Store processed event IDs.

Implement retries

LoyalPro will retry failed webhooks with exponential backoff for up to 72 hours.

Log everything

Keep detailed logs of received webhooks for debugging and auditing purposes.

Use HTTPS

Always use HTTPS endpoints in production. LoyalPro will not send webhooks to HTTP endpoints.

Next Steps

Best Practices

Production-ready integration patterns

Troubleshooting

Common issues and solutions

Was this page helpful?

Help us improve our documentation