Create Webhook

Registers a new webhook endpoint that will receive HTTP POST callbacks when subscribed events occur in the workspace.

POST /v1/webhooks

webhooks:write

Request Body

Parameter	Type	Required	Description
url	string	Yes	The HTTPS URL that will receive webhook payloads. Must use https://.
events	string[]	Yes	Array of event types to subscribe to. Use "*" to receive all events.
description	string	No	A human-readable description for this webhook.

Valid Events

Event	Description
*	Subscribe to all events.
link.created	A new short link was created.
link.updated	A short link was updated.
link.deleted	A short link was deleted.
link.scanned	A short link or QR code was scanned.
link.threshold	A link reached a scan count threshold.
bio.published	A Link-in-Bio page was published.
bio.unpublished	A Link-in-Bio page was unpublished.
asset.uploaded	A new asset upload was confirmed.
subscription.updated	The workspace subscription/plan changed.
test.ping	A test event for verifying webhook delivery.

Tip

After creating a webhook, send a test.ping event using the xQR dashboard to verify your endpoint is reachable and responding correctly.

Request Examples

curl

curl -X POST https://xqr.co/api/v1/webhooks \
  -H "Authorization: Bearer xqr_pk_a1b2c3d4.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/xqr",
    "events": ["link.created", "link.scanned"],
    "description": "Production link events"
  }'

TypeScript

const response = await fetch("https://xqr.co/api/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: "Bearer xqr_pk_a1b2c3d4.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/webhooks/xqr",
    events: ["link.created", "link.scanned"],
    description: "Production link events",
  }),
});

const { data } = await response.json();
console.log(data.id); // "wh_a1b2c3d4..."

Python

import httpx

response = httpx.post(
    "https://xqr.co/api/v1/webhooks",
    headers={
        "Authorization": "Bearer xqr_pk_a1b2c3d4.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com/webhooks/xqr",
        "events": ["link.created", "link.scanned"],
        "description": "Production link events",
    },
)

data = response.json()["data"]
print(data["id"])  # "wh_a1b2c3d4..."

Response

201 Created

The newly created webhook object.

{
  "data": {
    "id": "wh_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://example.com/webhooks/xqr",
    "events": ["link.created", "link.scanned"],
    "description": "Production link events",
    "enabled": true,
    "failure_count": 0,
    "created_at": "2026-03-21T14:30:00Z",
    "updated_at": "2026-03-21T14:30:00Z"
  },
  "meta": {
    "request_id": "req_8b9c0d1e2f3a4b56",
    "rate_limit": {
      "limit": 600,
      "remaining": 599,
      "reset": 1742572800
    }
  }
}