Webhooks & Callbacks

Receive real-time notifications when users complete offers. Configure your webhook endpoint to automatically credit user accounts.

Overview

When a user completes an offer or survey, Offerlia will send a POST request to your configured webhook URL with conversion details. You should process this callback server-side to credit the user's account.

Configuring Your Webhook

1. Set Webhook URL in Dashboard

Go to your publisher dashboard → Settings → Webhooks and enter your endpoint URL:

https://yourapp.com/api/webhooks/offerlia

2. Verify Webhook Secret

Each webhook request includes an X-Offerlia-Signature header for verification. Always verify this signature before processing callbacks.

Webhook Payload

Each webhook POST request includes the following JSON payload:

{
  "event": "conversion.approved",
  "conversion": {
    "id": "conv_abc123",
    "clickId": "click_xyz789",
    "userId": "user_456",
    "publisherId": "pub_abc123",
    "offerId": "offer_def456",
    "amount": 240,
    "currency": "USD",
    "status": "approved",
    "createdAt": "2025-12-15T12:00:00Z"
  },
  "timestamp": 1702641600
}

Event Types

Event	Description
`conversion.approved`	A conversion was approved and should be credited to the user
`conversion.rejected`	A conversion was rejected (fraud, invalid, etc.)
`conversion.pending`	A conversion is pending review

Signature Verification

Verify webhook authenticity using HMAC-SHA256:

// Node.js example
const crypto = require('crypto');

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

// In your webhook handler
const signature = req.headers['x-offerlia-signature'];
const isValid = verifyWebhookSignature(
  JSON.stringify(req.body),
  signature,
  process.env.OFFERLIA_WEBHOOK_SECRET
);

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

Response Format

Your webhook endpoint should return a 200 status code to acknowledge receipt:

{
  "success": true,
  "message": "Webhook processed"
}

If your endpoint returns a non-200 status, Offerlia will retry the webhook up to 3 times with exponential backoff.