All webhook payloads share a common envelope:

{
  "event": "stats.updated",
  "user_id": 123,
  "data": { ...event specific fields... },
  "sent_at": "2026-01-28T12:00:00Z"
}

stats.updated

Fired after each successful stats tracking run.

{
  "platform": "instagram",
  "account_id": "1234567890",
  "tracked_user_id": 42,
  "username": "my_brand",
  "follower_count": 10234,
  "following_count": 321,
  "posts_count": 456,
  "tracked_at": "2026-01-28T11:59:23Z"
}

follower.gained / follower.lost

Fired when follower change is detected between snapshots.

{
  "platform": "instagram",
  "tracked_username": "my_brand",
  "target_username": "new_fan",
  "target_user_id": "998877",
  "occurred_at": "2026-01-28T10:15:00Z",
  "change_date": "2026-01-28"
}

dm.sent / dm.failed

{
  "platform": "instagram",
  "tracked_username": "sender_account",
  "target_username": "lead_username",
  "occurred_at": "2026-01-28T09:00:00Z",
  "message": "Hey , quick question...",
  "device_id": "DEVICE_1",
  "error": "Optional error message for dm.failed"
}

job.completed / job.failed

{
  "job_id": 101,
  "job_type": "hashtag",
  "status": "finished",
  "started_at": "2026-01-28T08:00:00Z",
  "finished_at": "2026-01-28T08:30:00Z",
  "total_leads_stored": 250,
  "error": "Only present for job.failed"
}

Every webhook request is signed as: HMAC-SHA256(body, webhook_secret) and sent in X-Leadie-Signature.

Python example

import hmac
import hashlib

def verify_leadie_signature(body: bytes, header_sig: str, secret: str) -> bool:
    expected = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
    # Constant-time comparison
    return hmac.compare_digest(expected, header_sig)

Node.js example

const crypto = require('crypto');

function verifyLeadieSignature(body, headerSig, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computed, 'utf8'),
    Buffer.from(headerSig || '', 'utf8'),
  );
}

1. Trigger on follower.gained

1. Add a Webhook node in n8n, set method = POST.
2. Copy the n8n webhook URL into your Leadie webhook configuration and subscribe to follower.gained.
3. In n8n, parse the JSON body and use $.data.tracked_username, $.data.target_username, etc. in subsequent nodes.

2. Poll tracked stats

1. Add an HTTP Request node.
2. Method: GET, URL: https://your-domain.com/api/v1/stats.
3. Headers: Authorization: Bearer <LEADIE_API_KEY>.
4. Use the response to update Google Sheets, Slack, etc.

1. Webhook trigger scenario

1. Create a new scenario with the Webhooks module as the first step.
2. Choose Custom Webhook and copy the generated URL.
3. Paste the URL into a Leadie webhook and subscribe to the events you need (e.g. job.completed).
4. Run the scenario once to let Make sample a payload.

2. Scheduled stats sync

1. Add a HTTP module with GET /api/v1/tracker.
2. Use your API key in the Authorization header.
3. Map results into Airtable, Google Sheets or your CRM.

• List endpoints like /tracker/{id}/events use: ?page=1&per_page=50, response includes a pagination object.
• API request endpoints may use provider cursors (max_id, next_max_id).

Credit charging

• API requests consume credits.
• Pure Leadie reads (e.g. /me, /credits, list tracker events) do not consume credits.

Error codes

• 400: Validation errors (missing fields, bad filters, malformed dates).
• 401: Missing or invalid API key.
• 403: Ownership / access denied, or insufficient_credits for paid operations.
• 404: Resource not found.
• 429: Per-user per-minute API key rate limit exceeded.
• 500: Unexpected server errors.