Webhooks

Flock enables you to forward events from your referral campaigns directly to your specified webhook endpoints. By registering a webhook endpoint, Flock can send real-time event data to your application as soon as key actions occur in your campaigns. This is useful when you want to configure your own notifications or rewards system.

Flock uses HTTPS to deliver webhook events securely as JSON payloads, allowing your systems to respond to events such as successful referrals or claimed rewards. Webhooks are particularly helpful for integrating Flock with your backend systems, ensuring you can automate processes and stay updated with campaign activity in real time.

🚀 Getting Started

To start receiving webhook events from Flock in your application, follow these steps:

Create a webhook endpoint: Build an endpoint in your application to receive event data via HTTPS POST requests. This endpoint should be capable of processing JSON payloads.
Register your webhook endpoint: Log in to your Flock account at app.withflock.com, navigate to the Webhooks page, and add your endpoint.
Handle multiple events: You can configure your endpoint to receive multiple event types or create separate endpoints for specific events, depending on your needs.
Locate your webhook secret: After registering your endpoint, you can find the webhook secret key in your Flock account under the Secrets page. This key is required for verifying the authenticity of webhook requests.
Secure your endpoint: Use the webhook secret to implement signature verification. This ensures that the payloads are genuinely from Flock and protects your endpoint from unauthorized requests.

🔐 Secure Your Webhook Endpoint

To ensure that the event payloads sent to your webhook endpoint are legitimate and untampered, Flock includes a digital signature in the X-Flock-Signature header and a timestamp in the payload body of each webhook request. Follow these steps to verify the signature:

Step 1: Extract the Timestamp and Signature from the Request

When your endpoint receives a webhook event, the signature is sent in the X-Flock-Signature header, and the timestamp is included in the JSON payload body. Example header and payload: Header:

request

X-Flock-Signature: abcdef1234567890abcdef1234567890abcdef1234567890

Payload:

{
  "name": "invitee.accepted",
  "entity": "invitee",
  "entityId": "customer_67890",
  "data": {
    "campaignId": "campaign_12345",
    "referrer": {
      "id": "customer_12345"
    },
    "invitee": {
      "id": "customer_67890"
    },
    "inviteeReward": {
      "id": "c_reward_12345"
    },
    "referrerReward": {
      "id": "c_reward_67890"
    }
  },
  "timestamp": 1641234567
}

Step 2: Verify the Signature and Validate the Timestamp

To verify the signature and validate the timestamp, use the shared secret from the Secrets page in your Flock account. This ensures that the payloads are genuinely from Flock and protects against replay attacks by checking that the timestamp is within an acceptable range (e.g., 5 minutes from the current time).

import { FlockSDK } from '@wflock/node-flock';

// Initialize the SDK
const sdk = new FlockSDK({
  accessKey: 'your-service-access-key',
});

// Express.js route handler example
app.post('/webhooks/flock', (req, res) => {
  try {
    // Get the signature from the headers
    const signature = req.headers['x-flock-signature'];

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

    // Validate and construct the webhook event
    const event = sdk.webhooks.constructEvent({
      secret: 'your_webhook_secret',
      signature,
      payload: req.body,
      maxAge: 5 * 60 * 1000, // Optional: 5 minutes in milliseconds
    });

    // Handle the event based on its type
    switch (event.name) {
      case 'invitee.accepted':
        console.log(`Invitee ${event.data.invitee.id} accepted an invitation`);
        // Process the event...
        break;

      // Handle other event types...
      default:
        console.log(`Received unknown event type: ${event.name}`);
    }

    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error.message);
    return res.status(400).json({ error: error.message });
  }
});

import hmac
import hashlib

# Webhook Secret from your Flock account
secret = "your_webhook_secret"

payload = request.data.decode('utf-8')
signature = request.headers.get("X-Flock-Signature")

computedHash = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

if computedHash == signature:
  print("Signature verified successfully!")

  # Validate timestamp to prevent replay attacks
  five_minutes = 5 * 60 * 1000  # 5 minutes in milliseconds
  current_time = datetime.now()

  if abs(current_time - payload["timestamp"] * 1000) > five_minutes:
    raise Exception("Timestamp is too old!")

  return True
else:
  raise Exception("Invalid signature!")

Step 3: React to the Webhook Events

By implementing a webhook endpoint, you can react to events like invitee.accepted to send notifications to proper parties or even trigger your custom rewards.

Step 4: Implement a Retry Mechanism

Flock does not retry sending events if your webhook endpoint fails to acknowledge them. To ensure no events are missed, we recommend you implement a retry mechanism to handle errors or downtime in your systems, allowing you to reprocess events if needed.

Step 5: Respond to Flock

After verifying the signature and processing the payload, respond with a 200 OK status.

Webhook Payload

Payload Structure

When Flock sends a webhook event to your endpoint, the payload will have the following structure:

{
  "entity": "referral",
  "entityId": "referral_12345",
  "organizationId": "org_12345",
  "applicationId": "app_12345",
  "campaignId": "campaign_12345",
  "name": "referral.accepted",
  "description": "A referral was accepted",
  "timestamp": "2025-09-04T18:18:26-07:00"
}

Event Names

Flock can send the following webhook events:

Campaign Events

Event Name	Description
`campaign.launched`	A campaign has been launched
`campaign.ended`	A campaign has ended
`campaign.archived`	A campaign has been archived

Customer Events

Event Name	Description
`referrer.visited`	A referrer visited their referral link
`referrer.shared`	A referrer shared their referral link
`referrer.copied`	A referrer copied their referral link
`referrer.reward_claimed`	A referrer claimed their reward
`invitee.visited`	An invitee visited a referral link
`invitee.reward_claimed`	An invitee claimed their reward

Referral Events

Event Name	Description
`referral.accepted`	A referral was accepted
`referral.flagged`	A referral was flagged for potential fraud
`referral.rejected`	A referral was rejected

Reward Events

Event Name	Description
`reward.provisioned`	A reward was provisioned
`reward.fulfilled`	A reward was fulfilled

Registering for Events

You can register webhooks for specific events in the Flock dashboard. You can create multiple webhook endpoints, each listening for different events, or a single endpoint that handles all events.

For security reasons, always verify the signature of incoming webhook events as described in the “Secure Your Webhook Endpoint” section above.

Get Started

Customers Management

Checkpoints

SDKs

Additional Integration

Advanced

🚀 Getting Started

🔐 Secure Your Webhook Endpoint

Step 1: Extract the Timestamp and Signature from the Request

Step 2: Verify the Signature and Validate the Timestamp

Step 3: React to the Webhook Events

Step 4: Implement a Retry Mechanism

Step 5: Respond to Flock

Webhook Payload

Payload Structure

Event Names

Campaign Events

Customer Events

Referral Events

Reward Events

Registering for Events

​🚀 Getting Started

​🔐 Secure Your Webhook Endpoint

​Step 1: Extract the Timestamp and Signature from the Request

​Step 2: Verify the Signature and Validate the Timestamp

​Step 3: React to the Webhook Events

​Step 4: Implement a Retry Mechanism

​Step 5: Respond to Flock

​Webhook Payload

​Payload Structure

​Event Names

​Campaign Events

​Customer Events

​Referral Events

​Reward Events

​Registering for Events

🚀 Getting Started

🔐 Secure Your Webhook Endpoint

Step 1: Extract the Timestamp and Signature from the Request

Step 2: Verify the Signature and Validate the Timestamp

Step 3: React to the Webhook Events

Step 4: Implement a Retry Mechanism

Step 5: Respond to Flock

Webhook Payload

Payload Structure

Event Names

Campaign Events

Customer Events

Referral Events

Reward Events

Registering for Events