Webhook Endpoints

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.

​

🚀 Getting Started

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

1. 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.
2. Register your webhook endpoint: Log in to your Flock account at app.withflock.com, navigate to the Webhooks page, and add your endpoint.
3. Handle multiple events: You can configure your endpoint to receive multiple event types or create separate endpoints for specific events, depending on your needs.
4. 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.
5. 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:

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: Compute the Signature

To verify the signature, use the shared secret from the Secrets page in your Flock account to compute an HMAC-SHA256 hash of the concatenated timestamp and the JSON string of the data object.

const crypto = require('crypto');

// Webhook Secret from your Flock account
const secret = 'your_shared_secret';

// Extract fields from the request
const signature = request.headers['x-flock-signature'];
const payload = request.body;

// Compute the HMAC-SHA256 hash of the payload
const computedHash = crypto.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('hex');

// Compare the computed hash with the signature
if (computedHash === signature) {
console.log('Signature verified successfully!');
return true;
} else {
throw new Error('Invalid signature!');
}

​

Step 3: Validate the Timestamp

To protect against replay attacks, check that the timestamp is within an acceptable range (e.g., 5 minutes from the current time).

Here’s how you can validate the timestamp:

const fiveMinutes = 5 * 60 * 1000; // 5 minutes in milliseconds
const currentTime = Date.now();

if (Math.abs(currentTime - payload.timestamp \* 1000) > fiveMinutes) {
throw new Error('Timestamp is too old!');
}

​

Step 4: 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 5: 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 6: Respond to Flock

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