Webhooks

DaisyChain webhooks allow you to receive real-time notifications when events happen in your referral program. This guide explains how to set up and use webhooks effectively.

Overview

Webhooks are HTTP callbacks that notify your application when events occur in your DaisyChain referral program. Instead of polling our API for changes, webhooks push data to your application in real-time.

Common webhook use cases:

  • Receive notifications when new referrals are created
  • Update your systems when referrals are converted
  • Trigger reward fulfillment when payouts are approved
  • Monitor for potential fraud patterns

Setting Up Webhooks

To set up webhooks, navigate to the Webhooks section in your DaisyChain dashboard. You'll need to:

  1. Provide an endpoint URL - This is where DaisyChain will send webhook events. The endpoint must be publicly accessible and should respond with a 2xx status code.
  2. Select event types - Choose which events you want to receive notifications for.
  3. Set a secret key - This is used to verify that webhook requests are coming from DaisyChain.

Webhook Events

DaisyChain sends the following event types:

Event TypeDescription
referral.createdTriggered when a new referral is created
referral.convertedTriggered when a referral is marked as converted
referral.rejectedTriggered when a referral is rejected (e.g., due to fraud)
payout.createdTriggered when a new payout is created
payout.completedTriggered when a payout is completed
program.updatedTriggered when a referral program is updated

Webhook Payload

All webhook events share a common structure:

{
  "id": "evt_123456789",
  "type": "referral.converted",
  "created": "2023-05-15T14:23:45Z",
  "data": {
    // Event-specific data
  }
}

The data object contains event-specific information. For example, a referral.converted event includes:

{
  "id": "evt_123456789",
  "type": "referral.converted",
  "created": "2023-05-15T14:23:45Z",
  "data": {
    "referral_id": "ref_987654321",
    "program_id": "prog_123456",
    "referrer_id": "user_12345",
    "referee_id": "user_67890",
    "order_id": "order_54321",
    "order_amount": 99.99,
    "reward_amount": 10.00,
    "status": "converted",
    "conversion_date": "2023-05-15T14:23:45Z"
  }
}

Verifying Webhooks

To ensure webhook requests are coming from DaisyChain, we include a signature in the X-DaisyChain-Signature header. You should verify this signature before processing the webhook.

Node.js verification example:

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-daisychain-signature'];
  const webhookSecret = process.env.DAISYCHAIN_WEBHOOK_SECRET;
  
  // Create HMAC
  const hmac = crypto.createHmac('sha256', webhookSecret);
  const digest = hmac.update(req.body).digest('hex');
  
  // Compare signatures
  if (signature === digest) {
    const event = JSON.parse(req.body);
    // Process the webhook event
    console.log('Webhook verified:', event);
    res.status(200).send('Webhook received');
  } else {
    console.error('Webhook signature verification failed');
    res.status(403).send('Invalid signature');
  }
});

app.listen(3000, () => console.log('Webhook server running on port 3000'));

Best Practices

  • Respond quickly - Your endpoint should acknowledge receipt of the webhook by returning a 2xx status code as quickly as possible.
  • Process asynchronously - Handle the webhook processing in a background job to avoid timeouts.
  • Implement idempotency - Webhooks may be sent multiple times. Design your webhook handler to be idempotent.
  • Monitor failures - If DaisyChain cannot reach your endpoint, we'll retry with exponential backoff. Monitor for repeated failures.
  • Test in development - Use the webhook testing tool in your dashboard to send test events to your endpoint.