Guides
Webhooks

Webhooks

Receive real-time notifications when events happen in your PartyLayer application.

Setting Up

1. Create a Webhook Endpoint

Create an HTTP POST endpoint in your server:

// Express example
app.post('/api/webhooks/partylayer', (req, res) => {
  const payload = req.body;
  console.log('Event:', payload.type, payload.data);
  res.status(200).send('ok');
});

2. Register via Dashboard or API

Dashboard: Go to Webhooks > Create Webhook > Enter your URL and select event types.

API:

curl -X POST https://api.partylayer.io/v1/webhooks \
  -H "x-api-key: pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/api/webhooks/partylayer",
    "events": ["user.created", "tx.completed"]
  }'

Verifying Signatures

Every webhook delivery is signed with HMAC-SHA256. Always verify signatures in production.

import crypto from 'crypto';
 
function verifyWebhook(req, webhookSecret) {
  const signature = req.headers['x-partylayer-signature'];
  const timestamp = req.headers['x-partylayer-timestamp'];
  const body = JSON.stringify(req.body);
 
  // Check timestamp freshness (reject > 5 minutes old)
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (age > 300) {
    throw new Error('Webhook timestamp too old');
  }
 
  // Verify HMAC
  const expected = 'sha256=' +
    crypto
      .createHmac('sha256', webhookSecret)
      .update(`${timestamp}.${body}`)
      .digest('hex');
 
  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
 
  if (!isValid) {
    throw new Error('Invalid webhook signature');
  }
 
  return req.body;
}

Webhook Headers

Every delivery includes these headers:

HeaderDescription
X-PartyLayer-SignatureHMAC-SHA256 signature (sha256=hex)
X-PartyLayer-TimestampUnix timestamp of signing
X-PartyLayer-Event-IdUnique event ID for deduplication
Content-Typeapplication/json

Payload Format

{
  "id": "evt_abc123",
  "type": "user.created",
  "created_at": "2026-03-01T10:00:00.000Z",
  "api_version": "2026-03-01",
  "data": {
    "userId": "usr_xyz",
    "email": "alice@example.com",
    "partyId": "myapp_alice::1220abcd"
  }
}

Retry Policy

If your endpoint returns a non-2xx status or times out (30s), PartyLayer retries with exponential backoff:

AttemptDelay
11 minute
25 minutes
330 minutes
42 hours
524 hours

After 5 failed attempts, the delivery is moved to the Dead Letter Queue (DLQ). You can view and retry DLQ items from the dashboard.

Best Practices

  1. Return 200 quickly — Process webhooks asynchronously
  2. Verify signatures — Always check HMAC in production
  3. Handle duplicates — Use X-PartyLayer-Event-Id for idempotency
  4. Monitor DLQ — Set up alerts for failed deliveries
TransactionsGuest Sessions