Webhooks

Webhooks let you receive HTTP callbacks when events occur in your Storelayer project.

Supported Events

Event	Description
`customer.created`	New customer registered
`customer.updated`	Customer data changed
`wallet.credited`	Points added to wallet
`wallet.debited`	Points removed from wallet
`promotion.redeemed`	Promotion was used
`referral.completed`	Referral successfully applied
`event.processed`	Loyalty event was processed

Webhook Payload

{
  "id": "whk_abc123",
  "event": "wallet.credited",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "customerId": "cust_abc123",
    "amount": 500,
    "balance": 1500,
    "reason": "Purchase reward"
  }
}

Verifying Webhooks

All webhook requests include a signature header for verification:

X-Storelayer-Signature: sha256=abc123...

Verify the signature using your webhook secret:

import { createHmac } from 'crypto'

function verifyWebhook(payload, signature, secret) {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return `sha256=${expected}` === signature
}

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

1st retry: 1 minute
2nd retry: 5 minutes
3rd retry: 30 minutes
4th retry: 2 hours
5th retry: 24 hours

After 5 failed attempts, the webhook is marked as failed and can be manually retried from the dashboard.