Outbound Webhooks (Zupy → partner)

Receive real-time HTTP notifications when loyalty events occur in your customers’ accounts. Stay in sync with customer activity on your platform.

Prerequisites: Your API key (zupy_pk_*). See Getting Started if you don’t have these yet.

Two webhook surfaces — make sure you’re on the right one. This page covers the outbound flow: Zupy → your system. There’s a separate inbound flow (your system → Zupy) where you push order/customer data for processing — see Webhook Setup (Inbound). The URLs are deliberately distinct:

🟠 Outbound (this page): GET/PUT /api/v2/integrations/webhooks/ — you configure where Zupy should call.
🟢 Inbound: POST /api/v2/webhooks/integrations/{partner}/ — you call this; Zupy ingests.

Integrating via OpenDelivery? Partners on the OpenDelivery standard receive a different outbound surface: the OD LoyaltyEventEnvelope with X-App-Id / X-App-MerchantId / X-App-Signature headers (HMAC hex without the sha256= prefix, signed with your OAuth2 client_secret). This page documents the native webhook format only — don’t mix the two verification schemes. If you enable both surfaces, you will receive the same fact twice (e.g. points.earned and loyalty.points.earned); pick one.

How It Works

Zupy sends an HTTP POST to your configured webhook URL whenever a loyalty event occurs:

Event Occurs — Customer earns points, redeems a reward, coupon expires, etc.
Sign — Event payload is signed with HMAC-SHA256 using your secret
Send — HTTP POST to your webhook_url with signed payload
Retry — If your server returns non-2xx, we retry with exponential backoff

Event Types

Event	Trigger	Key Data
`customer.enrolled`	New customer joins loyalty program	`customer_id`, `program_id`, `name`, `phone`
`customer.tier_changed`	Customer moves loyalty tier	`customer_id`, `old_tier`, `new_tier`, `changed_at`
`points.earned`	Customer receives points	`customer_id`, `points_added`, `new_balance`, `source`, `reference_id`, `awarded_at`
`points.spent`	Customer’s points balance decreases	`customer_id`, `points_spent`, `new_balance`, `source`, `reference_id`, `spent_at`
`reward.redeemed`	Customer redeems reward → coupon created	`customer_id`, `coupon_code`, `reward_name`, `points_spent`, `valid_until`
`coupon.used`	Coupon validated/used at store	`customer_id`, `coupon_code`, `reward_name`, `used_at`
`coupon.cancelled`	Coupon cancelled	`customer_id`, `coupon_code`, `reward_name`, `cancelled_at`
`coupon.expiring`	Coupon expires in 3 days	`customer_id`, `coupon_code`, `reward_name`, `valid_until`, `expires_in_days`
`coupon.expired`	Coupon has expired	`customer_id`, `coupon_code`, `reward_name`, `expired_at`

Setup

Configure your webhook URL

Use the webhook management API to set your endpoint:

curl -X PUT https://api.zupy.com/api/v2/integrations/webhooks/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: zupy_pk_your_key_here" \
  -d '{
    "webhook_url": "https://your-server.com/webhooks/zupy",
    "webhook_events": ["customer.enrolled", "points.earned", "reward.redeemed", "coupon.used"]
  }'

The response includes your webhook_secret (masked). You’ll need this for signature verification.

Select events to receive

Choose which events trigger notifications. Leave empty to receive all events.Available events:

customer.enrolled
customer.tier_changed
points.earned
points.spent
reward.redeemed
coupon.used
coupon.cancelled
coupon.expiring
coupon.expired

Test your integration

Send a test ping to verify connectivity:

curl -X POST https://api.zupy.com/api/v2/integrations/webhooks/test/ \
  -H "X-API-Key: zupy_pk_your_key_here"

Response:

{
  "success": true,
  "status_code": 200,
  "error": null
}

Verify signatures

Implement signature verification in your webhook handler (see below).

Payload Format

Every webhook POST contains a JSON payload with this structure:

{
  "event": "customer.enrolled",
  "webhook_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-25T14:30:00.930009+00:00",
  "data": {
    "customer_id": "1651c60abc123def456",
    "program_id": "1651c60abcdef123456",
    "name": "João Silva",
    "phone": "+5514981242925",
    "enrolled_at": "2026-03-25T14:30:00.930009+00:00"
  }
}

Headers

Header	Description
`Content-Type`	Always `application/json`
`X-Webhook-Id`	Unique UUID for this delivery (use for idempotency)
`X-Webhook-Signature`	HMAC-SHA256 signature: `sha256=<hex_digest>`
`X-Webhook-Event`	Event type (e.g., `points.earned`)
`User-Agent`	Always `Zupy-Webhook/1.0`

Signature Verification

Verify the payload authenticity using HMAC-SHA256. This prevents spoofed requests.

Important: Use the raw request body bytes for verification — not the parsed JSON. The signature is computed over the exact bytes received.

import hmac
import hashlib

def verify_signature(body: bytes, signature_header: str, secret: str) -> bool:
    """
    Verify webhook signature from Zupy.
    
    Args:
        body: Raw request body (bytes)
        signature_header: Value of X-Webhook-Signature header (e.g., "sha256=abc123...")
        secret: Your webhook_secret from GET /integrations/webhooks/
    
    Returns:
        True if signature is valid
    """
    if not signature_header or not signature_header.startswith("sha256="):
        return False
    
    expected = hmac.new(
        secret.encode("utf-8"),
        body,
        hashlib.sha256
    ).hexdigest()
    
    received = signature_header.replace("sha256=", "")
    
    return hmac.compare_digest(expected, received)


# Flask example handler
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/zupy", methods=["POST"])
def handle_zupy_webhook():
    body = request.get_data()
    signature = request.headers.get("X-Webhook-Signature", "")
    secret = "whsec_your_secret_here"  # From webhook config
    
    if not verify_signature(body, signature, secret):
        return jsonify({"error": "Invalid signature"}), 401
    
    event = request.json
    # Process the event...
    
    return jsonify({"status": "ok"}), 200

const crypto = require('crypto');

function verifySignature(body, signatureHeader, secret) {
  if (!signatureHeader || !signatureHeader.startsWith('sha256=')) {
    return false;
  }
  
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  
  const received = signatureHeader.replace('sha256=', '');
  
  // Use timingSafeEqual to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(received)
  );
}

// Express.js example handler
const express = require('express');
const app = express();

app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf; // Keep raw body for signature verification
  }
}));

app.post('/webhooks/zupy', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = 'whsec_your_secret_here'; // From webhook config
  
  if (!verifySignature(req.rawBody, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  const event = req.body;
  // Process the event...
  
  res.status(200).json({ status: 'ok' });
});

app.listen(3000);

# Verify signature example (bash + openssl)
# This is for testing - in production use the Python/JS implementations above

# Extract signature and body, then verify
SIGNATURE="sha256=abc123..."  # From X-Webhook-Signature header
SECRET="whsec_your_secret"    # Your webhook secret
BODY='{"event":"customer.enrolled",...}'  # Raw request body

# Compute expected signature
EXPECTED=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

# Compare (simplified - use constant-time comparison in production)
if [ "$EXPECTED" = "${SIGNATURE#sha256=}" ]; then
    echo "Signature valid"
else
    echo "Signature invalid"
fi

Retry Behavior

If your server returns a non-2xx status code or times out, Zupy retries delivery:

Attempt	Delay	Description
1	Immediate	First delivery attempt
2	1 second	First retry (4^0)
3	4 seconds	Second retry (4^1)
4	16 seconds	Third retry (4^2)

Max delivery attempts: 4 (1 initial + 3 retries)
Timeout: 10 seconds per attempt
Backoff: Exponential base-4 (1s, 4s, 16s)
After exhaustion: Event is marked as exhausted and not retried again

Always respond with 2xx within 10 seconds. If you need longer processing, respond immediately and process asynchronously.

Idempotency

Use the X-Webhook-Id header to handle duplicate deliveries:

# Example: Deduplicate using X-Webhook-Id
def handle_webhook(request):
    webhook_id = request.headers.get("X-Webhook-Id")
    
    # Check if already processed
    if processed_ids.exists(webhook_id):
        return Response(status=200)  # Already processed
    
    # Process the event
    process_event(request.json)
    
    # Store the ID
    processed_ids.add(webhook_id)
    
    return Response(status=200)

The same event may be delivered multiple times (due to retries). Always check X-Webhook-Id before processing.

Event Payloads

customer.enrolled

Triggered when a new customer joins a loyalty program.

{
  "event": "customer.enrolled",
  "webhook_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-25T14:30:00.930009+00:00",
  "data": {
    "customer_id": "1651c60abc123def456",
    "program_id": "1651c60abcdef123456",
    "name": "João Silva",
    "phone": "+5514981242925",
    "enrolled_at": "2026-03-25T14:30:00.930009+00:00"
  }
}

points.earned

Triggered when a customer’s points balance increases.

{
  "event": "points.earned",
  "webhook_id": "7a3b9c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "timestamp": "2026-03-25T14:35:00.123456+00:00",
  "data": {
    "customer_id": "1651c60abc123def456",
    "points_added": 50,
    "new_balance": 350,
    "source": "integration:repediu",
    "reference_id": "repediu:247346204",
    "awarded_at": "2026-03-25T14:35:00.123456+00:00"
  }
}

reward.redeemed

Triggered when a customer redeems a reward (coupon created).

{
  "event": "reward.redeemed",
  "webhook_id": "d35b1d07-884c-46b7-a502-cd014a31e360",
  "timestamp": "2026-03-25T15:00:00.456789+00:00",
  "data": {
    "customer_id": "1651c60abc123def456",
    "coupon_code": "REWARD-ABC123XYZ",
    "reward_id": "1651c60abcdef789012",
    "reward_name": "Pizza Média Grátis",
    "points_spent": 200,
    "valid_until": "2026-04-25T15:00:00.456789+00:00"
  }
}

coupon.used

Triggered when a coupon is validated or used at a store.

{
  "event": "coupon.used",
  "webhook_id": "e46c2e18-995d-57c8-b613-de125b42f471",
  "timestamp": "2026-03-25T16:00:00.789012+00:00",
  "data": {
    "customer_id": "1651c60abc123def456",
    "coupon_code": "REWARD-ABC123XYZ",
    "reward_name": "Pizza Média Grátis",
    "used_at": "2026-03-25T16:00:00.789012+00:00"
  }
}

coupon.expiring

Triggered 3 days before a coupon expires.

{
  "event": "coupon.expiring",
  "webhook_id": "f57d3f29-aa6e-68d9-c724-ef236c53g582",
  "timestamp": "2026-03-22T08:00:00.345678+00:00",
  "data": {
    "customer_id": "1651c60abc123def456",
    "coupon_code": "REWARD-ABC123XYZ",
    "reward_name": "Pizza Média Grátis",
    "valid_until": "2026-03-25T23:59:59.000000+00:00",
    "expires_in_days": 3
  }
}

customer.tier_changed

Triggered when a customer moves loyalty tier.

{
  "event": "customer.tier_changed",
  "webhook_id": "b79f5h4b-cc8g-8afb-e946-gh458e75i7a4",
  "timestamp": "2026-03-25T17:00:00.123456+00:00",
  "data": {
    "customer_id": "1651c60abc123def456",
    "old_tier": "potential_loyalist",
    "new_tier": "loyal_customer",
    "changed_at": "2026-03-25T17:00:00.123456+00:00"
  }
}

points.spent

Triggered when a customer’s points balance decreases.

{
  "event": "points.spent",
  "webhook_id": "c8ag6i5c-dd9h-9bgc-fa57-hi569f86j8b5",
  "timestamp": "2026-03-25T17:30:00.456789+00:00",
  "data": {
    "customer_id": "1651c60abc123def456",
    "points_spent": 200,
    "new_balance": 150,
    "source": "reward_redemption",
    "reference_id": "1651c60abcdef789012",
    "spent_at": "2026-03-25T17:30:00.456789+00:00"
  }
}

coupon.cancelled

Triggered when a coupon is cancelled.

{
  "event": "coupon.cancelled",
  "webhook_id": "d9bh7j6d-eeai-achd-gb68-ij67ag97k9c6",
  "timestamp": "2026-03-25T18:00:00.789012+00:00",
  "data": {
    "customer_id": "1651c60abc123def456",
    "coupon_code": "REWARD-ABC123XYZ",
    "reward_name": "Pizza Média Grátis",
    "cancelled_at": "2026-03-25T18:00:00.789012+00:00"
  }
}

coupon.expired

Triggered when a coupon passes its expiration date.

{
  "event": "coupon.expired",
  "webhook_id": "a68e4g3a-bb7f-79ea-d835-fg347d64h693",
  "timestamp": "2026-03-26T08:00:00.567890+00:00",
  "data": {
    "customer_id": "1651c60abc123def456",
    "coupon_code": "REWARD-ABC123XYZ",
    "reward_name": "Pizza Média Grátis",
    "expired_at": "2026-03-25T23:59:59.000000+00:00"
  }
}

Best Practices

Best Practices & FAQ

Respond quickly

Always return 2xx within 10 seconds. If you need longer processing, respond immediately and process asynchronously.

Verify signatures

Never process a webhook without verifying the signature first. This prevents spoofed requests.

Use X-Webhook-Id for deduplication

Store processed webhook IDs and skip duplicates. Retries may send the same event multiple times.

Return 2xx even for async processing

As long as you received the webhook, return 2xx. Don’t wait for your downstream processing to complete.

Log failed verifications

Keep logs of failed signature verifications for debugging security issues.

Webhook Management API Reference

Get Webhook Configuration

GET /api/v2/integrations/webhooks/

Response:

{
  "webhook_url": "https://your-server.com/webhooks/zupy",
  "webhook_events": ["customer.enrolled", "points.earned"],
  "webhook_secret": "****5678",
  "available_events": [
    "customer.enrolled",
    "customer.tier_changed",
    "points.earned",
    "points.spent",
    "reward.redeemed",
    "coupon.used",
    "coupon.cancelled",
    "coupon.expiring",
    "coupon.expired"
  ]
}

Update Webhook Configuration

PUT /api/v2/integrations/webhooks/

Request Body:

{
  "webhook_url": "https://your-server.com/webhooks/zupy",
  "webhook_events": ["customer.enrolled", "points.earned", "reward.redeemed"]
}

Response:

{
  "webhook_url": "https://your-server.com/webhooks/zupy",
  "webhook_events": ["customer.enrolled", "points.earned", "reward.redeemed"],
  "webhook_secret": "****5678",
  "available_events": [
    "customer.enrolled",
    "customer.tier_changed",
    "points.earned",
    "points.spent",
    "reward.redeemed",
    "coupon.used",
    "coupon.cancelled",
    "coupon.expiring",
    "coupon.expired"
  ]
}

Test Webhook Delivery

POST /api/v2/integrations/webhooks/test/

Response:

{
  "success": true,
  "status_code": 200,
  "error": null
}

Introduction

Guides

Outbound Webhooks (Zupy → partner)

How It Works

Event Types

Setup

Payload Format

Headers

Signature Verification

Retry Behavior

Idempotency

Event Payloads

Best Practices

Respond quickly

Verify signatures

Use X-Webhook-Id for deduplication

Return 2xx even for async processing

Log failed verifications

Webhook Management API Reference

Get Webhook Configuration

Update Webhook Configuration

Test Webhook Delivery

​How It Works

​Event Types

​Setup

​Payload Format

​Headers

​Signature Verification

​Retry Behavior

​Idempotency

​Event Payloads

​Best Practices

​Respond quickly

​Verify signatures

​Use X-Webhook-Id for deduplication

​Return 2xx even for async processing

​Log failed verifications

​Webhook Management API Reference

​Get Webhook Configuration

​Update Webhook Configuration

​Test Webhook Delivery

How It Works

Event Types

Setup

Payload Format

Headers

Signature Verification

Retry Behavior

Idempotency

Event Payloads

Best Practices

Respond quickly

Verify signatures

Use X-Webhook-Id for deduplication

Return 2xx even for async processing

Log failed verifications

Webhook Management API Reference

Get Webhook Configuration

Update Webhook Configuration

Test Webhook Delivery