Webhooks Integration Guide: Synchronize Scan Data in Real Time

What Webhooks Do for Your Business

Webhooks deliver real-time data from QR code scan events directly to your external servers, CRMs, messaging platforms, or database systems. Unlike API polling (which requests updates periodically), webhooks push scan telemetry instantly when the scan occurs.

This allows operations to:

1. Trigger CRM customer lead entry.
2. Synchronize scan telemetry with custom reporting databases.
3. Power real-time Slack, Discord, or Teams alerts.
4. Auto-update dispatch or loyalty system records.

Plan Tier Availability

Webhooks are advanced integration tools. They are available on:

• Pro+ and Pro++ plans
• Team, Team+, and Team++ plans
• Enterprise plans

Trial and standard Pro plans do not support webhook registration.

Step-by-Step Webhook Setup

Follow this step-by-step workflow to configure your first active endpoint:

Step 1: Open the Webhooks Center

Go to Webhooks from your dashboard sidebar navigation.

Step 2: Register a New Endpoint

1. Click Add Webhook in the upper-right corner.
2. Enter a descriptive Webhook Name (e.g., "Leads Database Sync").
3. Input the Destination POST URL (e.g., https://api.yourcompany.com/hooks/qr). The URL must be absolute and use secure HTTPS.
4. Click Save Webhook.

Step 3: Verify the Connection

Once saved, the status will show as Active. Test-scan one of your dynamic QR codes using a mobile device, then check your server logs or view the delivery history log at the bottom of the Webhooks page to verify that the request was successfully received (HTTP 200).

Webhook JSON Event Payload Reference

All webhooks receive HTTP POST requests with a Content-Type: application/json header and a header identifier X-QR-Webhook-Event: qr.scan.

Example JSON payload structure:

{
  "event": "qr.scan",
  "timestamp": "2026-06-03T08:30:12.441Z",
  "qrCode": {
    "id": "e44d32f5-b283-4a18-a6d1-dbfb1889a710",
    "name": "Summer Menu QR",
    "type": "website",
    "url": "https://restaurant.com/menu"
  },
  "scan": {
    "id": "0d20d7be-b214-41d9-81a1-9cb67cf6551b",
    "ipAddress": "197.80.201.44",
    "country": "South Africa",
    "city": "Cape Town",
    "device": "MOBILE",
    "deviceModel": "iPhone 15",
    "os": "iOS",
    "browser": "Safari",
    "referrer": "https://instagram.com",
    "utmSource": "instagram",
    "utmMedium": "social",
    "utmCampaign": "summer_promo"
  }
}

Security and Production Guidelines

1. Enforce HTTPS: Always use secure https:// endpoints to prevent interception of scan analytics data.
2. Payload Size: The system sends lightweight JSON objects (~1KB) per scan to prevent network bottlenecks.
3. Response Timeout: Webhook calls have a strict 3-second timeout. Your endpoint must respond with an HTTP 200 or 201 status code within this window, or the call will be marked as failed.
4. Asynchronous Dispatching: Webhook dispatches are processed asynchronously and do not delay user redirection.

Troubleshooting Delivery Failures

If you notice failed webhook deliveries in your log dashboard, check these common causes in order:

Related Guides

• API keys and automation setup: api-keys-and-api-calls-explained.
• No-code zapier quickstart: api-quickstart-non-developers.
• Feature limits by subscription: team-vs-pro-plan-capabilities.