Webhooks

Stop polling the API for updates. Webhooks push events to your server in real-time. Profile created? You get notified instantly. Proxy failed? You know immediately.

How Webhooks Work

When an event happens (profile launched, proxy failed, team member added), we send an HTTP POST request to your webhook URL.

Your server receives the event, processes it, and responds with 200 OK.

If we don't get 200 OK, we retry up to 3 times with exponential backoff.

Setting Up Webhooks

Configure webhooks in your dashboard: Settings → Webhooks → Add Endpoint.

Or via API:

POST https://api.multilogin.io/v1/webhooks

{
  "url": "https://yourdomain.com/webhook",
  "events": ["profile.created", "profile.launched", "proxy.failed"],
  "secret": "whsec_your_secret_key_here"
}

The secret is used to verify webhook authenticity. Generate a random string (32+ characters).

Available Events

Subscribe to specific events or use * for all events.

Webhook Payload Format

All webhooks follow this structure:

{
  "id": "evt_abc123xyz",
  "type": "profile.created",
  "created_at": "2024-02-22T10:30:00Z",
  "data": {
    "profile": {
      "id": "prof_xyz789",
      "name": "Facebook Account 1",
      "browser": "chromium",
      "fingerprint_template": "social_media",
      "created_at": "2024-02-22T10:30:00Z"
    }
  }
}

Field Descriptions:

• id - Unique event ID (for deduplication)
• type - Event type (e.g., profile.created)
• created_at - When event occurred (ISO 8601)
• data - Event-specific payload

Handling Webhooks

Node.js/Express Example:

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

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
  // Verify signature
  const signature = req.headers['x-multilogin-signature'];
  const payload = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

  // Process event
  const event = req.body;

  switch (event.type) {
    case 'profile.created':
      console.log('New profile:', event.data.profile.name);
      break;
    case 'proxy.failed':
      console.log('Proxy failed:', event.data.proxy.host);
      // Send alert to team
      break;
    case 'profile.launched':
      console.log('Profile launched:', event.data.profile.id);
      break;
  }

  // Respond with 200 OK
  res.status(200).send('Received');
});

app.listen(3000);

Python/Flask Example:

import os
import hmac
import hashlib
from flask import Flask, request

app = Flask(__name__)
WEBHOOK_SECRET = os.getenv('WEBHOOK_SECRET')

@app.route('/webhook', methods=['POST'])
def webhook():
    # Verify signature
    signature = request.headers.get('X-Multilogin-Signature')
    payload = request.get_data()

    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if signature != expected_signature:
        return 'Invalid signature', 401

    # Process event
    event = request.get_json()

    if event['type'] == 'profile.created':
        print(f"New profile: {event['data']['profile']['name']}")
    elif event['type'] == 'proxy.failed':
        print(f"Proxy failed: {event['data']['proxy']['host']}")

    return 'Received', 200

if __name__ == '__main__':
    app.run(port=3000)

Signature Verification

Always verify webhook signatures. This prevents unauthorized requests.

We include X-Multilogin-Signature header with each webhook:

X-Multilogin-Signature: abc123def456...

Compute expected signature:

1. Get raw request body (JSON string, no parsing)
2. Compute HMAC-SHA256 using your webhook secret
3. Compare with signature header
4. Reject if they don't match

Retry Logic

If your endpoint returns non-200 status or times out, we retry:

• Attempt 1: Immediate delivery
• Attempt 2: 5 seconds later
• Attempt 3: 25 seconds later
• Attempt 4: 125 seconds later (final)

After 4 failed attempts, we mark the webhook as failed and stop retrying.

Failed webhooks are logged in your dashboard: Settings → Webhooks → Failed Deliveries.

Idempotency

Webhooks can be delivered more than once. Handle duplicates gracefully.

Use event.id to track processed events:

const processedEvents = new Set();

app.post('/webhook', (req, res) => {
  const event = req.body;

  // Check if already processed
  if (processedEvents.has(event.id)) {
    return res.status(200).send('Already processed');
  }

  // Process event
  processEvent(event);

  // Mark as processed
  processedEvents.add(event.id);

  res.status(200).send('Received');
});

In production, use a database or Redis to track processed event IDs.

Testing Webhooks

Test webhook integration before going live.

Use webhook.site for testing:

1. Visit webhook.site → Copy your unique URL
2. Add URL as webhook endpoint in Multilogin dashboard
3. Trigger an event (create a profile)
4. Check webhook.site to see the payload

Send test webhooks via API:

POST https://api.multilogin.io/v1/webhooks/:id/test

{
  "event_type": "profile.created"
}

This sends a sample webhook to your endpoint for testing.

Best Practices

• Respond quickly: Return 200 OK within 5 seconds. Do heavy processing async.
• Use HTTPS: Webhook URLs must use HTTPS in production.
• Handle duplicates: Track event IDs to prevent double-processing.
• Log everything: Log all received webhooks for debugging.
• Monitor failures: Alert when webhooks fail repeatedly.
• Rotate secrets: Change webhook secrets quarterly.