Webhooks Overview

Webhooks allow your application to receive real-time HTTP callbacks when events occur in your xQR workspace — like a link being scanned, a bio page published, or an asset uploaded.

How It Works

1. You register a webhook endpoint URL and the events you want to receive
2. When a matching event occurs, xQR sends a POST request to your URL
3. The payload is signed with HMAC-SHA256 so you can verify authenticity
4. If delivery fails, xQR retries with exponential backoff

Payload Format

Every webhook delivery sends a JSON payload:

{
  "event": "link.created",
  "timestamp": "2026-03-21T10:30:00Z",
  "data": {
    "link_id": "550e8400-e29b-41d4-a716-446655440000",
    "short_code": "my-link",
    "destination": "https://example.com"
  }
}

Headers

Each delivery includes these headers:

Header	Description
Content-Type	application/json
X-XQR-Event	Event type (e.g. link.created)
X-XQR-Delivery	Unique delivery ID (UUID)
X-XQR-Signature	HMAC-SHA256 signature: sha256={hex_digest}
User-Agent	xQR-Webhooks/1.0

Managing Webhooks

Create and manage webhooks via:

• Dashboard: Settings → Developers → Webhooks
• API: POST /v1/webhooks
• MCP: create_webhook tool (coming in Phase 2)

Tip

Use the Test button in the dashboard to send a test.ping event to your endpoint and verify connectivity before going live.

Plan Limits

Plan	Webhook Endpoints
Free	0
Pro	3
Business	20
Enterprise	Unlimited