Event types

Webhooks are a great way to get real-time notifications on events that happen in your CodeQR project. Webhooks on CodeQR follow the following format:

webhook-payload.json

{
  "id": "evt_KleiO4HBwZFbO1vZLWIPZ2AtX", // The event ID
  "event": "link.created", // The event type
  "createdAt": "2024-08-26T16:41:52.346Z", // The timestamp of when the event was created
  "data": {
    // Event payload
  }
}

There are four types of webhook events you can listen to:

Project-level events
Link-level events
QR Code-level events
Page-level events

Plan requirements for subscribing. Receiving webhook deliveries is not plan-gated, but the events you can subscribe to are:

CRUD events (link.*, qrcode.*, page.* created/updated/deleted), lead.created, and sale.created require the Pro plan or above.
High-volume events — link.clicked, qrcode.scanned, and page.visited — require the Business plan or above.
Attaching a specific link, QR Code, or Page to a webhook also requires the Business plan or above.

Project-level events

These events are triggered in the context of your entire project:

link.created
link.updated
link.deleted
qrcode.created
qrcode.updated
qrcode.deleted
page.created
page.updated
page.deleted
lead.created
sale.created

`link.created`

This event is triggered when a new link is created in your CodeQR project. The event payload contains the created link’s details. Here’s an example payload:

Sample payload

link.created

{
  "id": "evt_KleiO4HBwZFbO1vZLWIPZ2AtX",
  "event": "link.created",
  "createdAt": "2024-08-26T16:41:52.346Z",
  "data": {
    "id": "cm0b87844000dismqhkviju54",
    "domain": "codeqr.link",
    "key": "sOvvXDT",
    "externalId": null,
    "url": "https://github.com/stack-auth/stack",
    "trackConversion": false,
    "archived": false,
    "expiresAt": null,
    "expiredUrl": null,
    "password": null,
    "proxy": false,
    "title": null,
    "description": null,
    "image": null,
    "video": null,
    "rewrite": false,
    "doIndex": false,
    "ios": null,
    "android": null,
    "geo": null,
    "publicStats": false,
    "tagId": null,
    "tags": [],
    "comments": null,
    "shortLink": "https://codeqr.link/9KUP86d",
    "qrCode": "https://api.codeqr.io/qr?url=https://codeqr.link/9KUP86d?qr=1",
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_term": null,
    "utm_content": null,
    "userId": "cm022rkcw0000ikt14mscg9sg",
    "projectId": "cm022sis60003ikt1syy7kfhl",
    "clicks": 0,
    "lastClicked": null,
    "leads": 0,
    "sales": 0,
    "saleAmount": 0,
    "createdAt": "2024-08-26T16:41:52.084Z",
    "updatedAt": "2024-08-26T16:41:52.084Z",
    "projectId": "cm022sis60003ikt1syy7kfhl"
  }
}

`link.updated`

This event is triggered when a link is updated in your CodeQR project. The event payload contains the updated link’s details. Here’s an example payload:

Sample payload

link.updated

{
  "id": "event_KleiO4HBwZFbO1vZLWIPZ2AtX",
  "event": "link.updated",
  "createdAt": "2024-08-26T16:41:52.346Z",
  "data": {
    "id": "cm0b87844000dismqhkviju54",
    "domain": "codeqr.link",
    "key": "sOvvXDT",
    "externalId": null,
    "url": "https://github.com/stack-auth/stack",
    "trackConversion": false,
    "archived": false,
    "expiresAt": null,
    "expiredUrl": null,
    "password": null,
    "proxy": false,
    "title": null,
    "description": null,
    "image": null,
    "video": null,
    "rewrite": false,
    "doIndex": false,
    "ios": null,
    "android": null,
    "geo": null,
    "publicStats": false,
    "tagId": null,
    "tags": [],
    "comments": null,
    "shortLink": "https://codeqr.link/9KUP86d",
    "qrCode": "https://api.codeqr.io/qr?url=https://codeqr.link/9KUP86d?qr=1",
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_term": null,
    "utm_content": null,
    "userId": "cm022rkcw0000ikt14mscg9sg",
    "projectId": "cm022sis60003ikt1syy7kfhl",
    "clicks": 0,
    "lastClicked": null,
    "leads": 0,
    "sales": 0,
    "saleAmount": 0,
    "createdAt": "2024-08-26T16:41:52.084Z",
    "updatedAt": "2024-08-26T16:41:52.084Z",
    "projectId": "cm022sis60003ikt1syy7kfhl"
  }
}

`link.deleted`

This event is triggered when a link is deleted in your CodeQR project. The event payload contains the deleted link’s details. Here’s an example payload:

Sample payload

link.deleted

{
  "id": "evt_KleiO4HBwZFbO1vZLWIPZ2AtX",
  "event": "link.deleted",
  "createdAt": "2024-08-26T16:41:52.346Z",
  "data": {
    "id": "cm0b87844000dismqhkviju54",
    "domain": "codeqr.link",
    "key": "sOvvXDT",
    "externalId": null,
    "url": "https://github.com/stack-auth/stack",
    "trackConversion": false,
    "archived": false,
    "expiresAt": null,
    "expiredUrl": null,
    "password": null,
    "proxy": false,
    "title": null,
    "description": null,
    "image": null,
    "video": null,
    "rewrite": false,
    "doIndex": false,
    "ios": null,
    "android": null,
    "geo": null,
    "publicStats": false,
    "tagId": null,
    "tags": [],
    "comments": null,
    "shortLink": "https://codeqr.link/9KUP86d",
    "qrCode": "https://api.codeqr.io/qr?url=https://codeqr.link/9KUP86d?qr=1",
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_term": null,
    "utm_content": null,
    "userId": "cm022rkcw0000ikt14mscg9sg",
    "projectId": "cm022sis60003ikt1syy7kfhl",
    "clicks": 0,
    "lastClicked": null,
    "leads": 0,
    "sales": 0,
    "saleAmount": 0,
    "createdAt": "2024-08-26T16:41:52.084Z",
    "updatedAt": "2024-08-26T16:41:52.084Z",
    "projectId": "cm022sis60003ikt1syy7kfhl"
  }
}

`qrcode.created`

This event is triggered when a new QR code is created in your CodeQR project. The event payload contains the created QR code’s details (under data.qrcode).

Sample payload

qrcode.created

{
  "id": "evt_KleiO4HBwZFbO1vZLWIPZ2AtX",
  "event": "qrcode.created",
  "createdAt": "2024-08-26T16:41:52.346Z",
  "data": {
    "qrcode": {
      "id": "cm0pie2xy0007zayvaghkb7d6",
      "domain": "expol.ink",
      "key": "rXUSTPx1tic3-qr",
      "archived": false,
      "static": false,
      "type": "url",
      "url": "https://app.codeqr.io/",
      "userId": "clv4ckurp0000nircotd5umkn",
      "projectId": "cm0bfj5eg000045ruzb5o8tar",
      "scans": 1,
      "shortLink": "https://expol.ink/rXUSTPx1tic3-qr",
      "createdAt": "2024-09-05T16:35:54.597Z",
      "updatedAt": "2024-09-05T16:35:54.597Z"
    }
  }
}

`qrcode.updated`

This event is triggered when a QR code is updated in your CodeQR project. The event payload contains the updated QR code’s details (under data.qrcode).

`qrcode.deleted`

This event is triggered when a QR code is deleted in your CodeQR project. The event payload contains the deleted QR code’s details (under data.qrcode).

`page.created`

This event is triggered when a new page is created in your CodeQR project. The event payload contains the created page’s details (under data.page).

Sample payload

page.created

{
  "id": "evt_KleiO4HBwZFbO1vZLWIPZ2AtX",
  "event": "page.created",
  "createdAt": "2024-08-26T16:41:52.346Z",
  "data": {
    "page": {
      "id": "cm0snvcxr002jp80474b2dckg",
      "domain": "expol.ink",
      "key": "p/pHs20VCe8V",
      "name": "Deixe seu feedback",
      "type": "feedback",
      "projectId": "cm0bfj5eg000045ruzb5o8tar",
      "userId": "clv4ckurp0000nircotd5umkn",
      "views": 1,
      "createdAt": "2024-09-07T21:32:37.309Z",
      "updatedAt": "2024-09-07T21:32:51.471Z"
    }
  }
}

`page.updated`

This event is triggered when a page is updated in your CodeQR project. The event payload contains the updated page’s details (under data.page).

`page.deleted`

This event is triggered when a page is deleted in your CodeQR project. The event payload contains the deleted page’s details (under data.page).

`lead.created`

This event is triggered when a new lead is created via CodeQR Conversions. The event payload contains the following:

eventName: The name of the event that was tracked.
customer: Details about the customer that signed up.
interaction: The click/scan/view event that led to the lead (same shape as data.interaction for link.clicked, qrcode.scanned, page.visited).
link / qrcode / page: Details about the referral resource the lead is associated with, when applicable.

Here’s an example payload:

Sample payload

lead.created

{
  "id": "evt_P343bmyae40ALQYr5HT4vRXRd",
  "event": "lead.created",
  "createdAt": "2024-08-30T09:53:50.343Z",
  "data": {
    "eventName": "Sign up",
    "customer": {
      "id": "oU5P0SqI8fpwx5bxw1",
      "name": "John",
      "email": "john@example.com",
      "avatar": "https://example.com/john.jpeg"
    },
    "interaction": {
      "id": "d0UtZqE0BZuBPrJS",
      "url": "https://github.com/codeqr-io/codeqr",
      "ip": "63.141.57.109",
      "continent": "NA",
      "country": "US",
      "city": "San Francisco",
      "device": "Desktop",
      "browser": "Chrome",
      "os": "Mac OS",
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36",
      "bot": false,
      "qr": false,
      "referer": "(direct)"
    },
    "link": {
      "id": "cm0faqkyn0001txvfwjfeq7gl",
      "domain": "codeqr.link",
      "key": "79ys3WA",
      "externalId": null,
      "url": "https://github.com/codeqr-io/codeqr",
      "trackConversion": true,
      "archived": false,
      "expiresAt": null,
      "expiredUrl": null,
      "password": null,
      "proxy": false,
      "title": null,
      "description": null,
      "image": null,
      "video": null,
      "rewrite": false,
      "doIndex": false,
      "ios": null,
      "android": null,
      "geo": null,
      "publicStats": false,
      "comments": null,
      "shortLink": "https://codeqr.link/9KUP86d",
      "qrCode": "https://api.codeqr.io/qr?url=https://codeqr.link/9KUP86d?qr=1",
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null,
      "utm_term": null,
      "utm_content": null,
      "userId": "cm022rkcw0000ikt14mscg9sg",
      "projectId": "cm022sis60003ikt1syy7kfhl",
      "clicks": 10,
      "lastClicked": "2024-08-30T07:45:09.000Z",
      "leads": 5,
      "sales": 0,
      "saleAmount": 0,
      "createdAt": "2024-08-29T13:03:59.098Z",
      "updatedAt": "2024-08-30T09:53:49.505Z"
    }
  }
}

`sale.created`

This event is triggered when a new sale is tracked via CodeQR Conversions. The event payload contains the following:

eventName: Optional; the name of the event that was tracked.
customer: Details about the customer that made the purchase.
interaction: Optional; the click/scan/view event that led to the sale (when available; e.g. not sent from Stripe checkout).
link / qrcode / page: Details about the referral resource the sale is associated with, when applicable.
sale: Amount, currency, payment processor, invoice ID.

Here’s an example payload:

Sample payload

sale.created

{
  "id": "evt_WHjyHhqsfYOrlJOOVJSoHXysD",
  "event": "sale.created",
  "createdAt": "2024-08-30T09:57:51.245Z",
  "data": {
    "eventName": "Purchased",
    "customer": {
      "id": "cm0gjdvr20001dkbha2n9gt2b",
      "name": "John",
      "email": "john@example.com",
      "avatar": "https://example.com/john.jpeg"
    },
    "interaction": {
      "id": "d0UtZqE0BZuBPrJS",
      "url": "https://github.com/codeqr-io/codeqr",
      "ip": "63.141.57.109",
      "continent": "NA",
      "country": "US",
      "city": "San Francisco",
      "device": "Desktop",
      "browser": "Chrome",
      "os": "Mac OS",
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36",
      "bot": false,
      "qr": false,
      "referer": "(direct)"
    },
    "link": {
      "id": "cm0faqkyn0001txvfwjfeq7gl",
      "domain": "codeqr.link",
      "key": "79ys3WA",
      "externalId": null,
      "url": "https://github.com/codeqr-io/codeqr",
      "trackConversion": true,
      "archived": false,
      "expiresAt": null,
      "expiredUrl": null,
      "password": null,
      "proxy": false,
      "title": null,
      "description": null,
      "image": null,
      "video": null,
      "rewrite": false,
      "doIndex": false,
      "ios": null,
      "android": null,
      "geo": null,
      "publicStats": false,
      "comments": null,
      "shortLink": "https://codeqr.link/9KUP86d",
      "qrCode": "https://api.codeqr.io/qr?url=https://codeqr.link/9KUP86d?qr=1",
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null,
      "utm_term": null,
      "utm_content": null,
      "userId": "cm022rkcw0000ikt14mscg9sg",
      "projectId": "cm022sis60003ikt1syy7kfhl",
      "clicks": 10,
      "lastClicked": "2024-08-30T07:45:09.000Z",
      "leads": 5,
      "sales": 1,
      "saleAmount": 20000,
      "createdAt": "2024-08-29T13:03:59.098Z",
      "updatedAt": "2024-08-30T09:57:50.891Z"
    },
    "sale": {
      "amount": 4500,
      "currency": "usd",
      "payment_processor": "stripe",
      "invoice_id": null
    }
  }
}

Payload field: `interaction`

“Interaction” is not an event type. It is a field inside the data object that we send for click, scan, and view events. We always use the same key data.interaction and the same structure (the click-event shape: timestamp, clickId, url, ip, continent, country, city, device, browser, os, ua, bot, qr, referer, etc.) for:

Link-level link.clicked — data.interaction (click event) + data.link
QR Code-level qrcode.scanned — data.interaction (scan event, same shape) + data.qrcode
Page-level page.visited — data.interaction (view event, same shape) + optionally data.page
Project-level lead.created — data.interaction (the click that led to the lead) + data.customer, data.link / data.qrcode / data.page

We do not send data.click, data.scan, or data.view; we send data.interaction for all of these. We do not send a separate webhook event named “interaction”. Only the event types listed in this document are sent.

Link-level events

Due to the high volume nature of these events, these events are scoped to a specific link. This means that you need to specify the link when creating a webhook – though you can select multiple links for the same webhook if you’d like.

`link.clicked`

This event is triggered when a user clicks on a link. The event payload contains data.interaction (the click event) and data.link (full link details). Here’s an example payload:

Sample payload

link.clicked

{
  "id": "evt_b9ywgxWqai2glUpCQjclB17kM",
  "event": "link.clicked",
  "createdAt": "2024-08-30T10:16:13.149Z",
  "data": {
    "eventName": "Link clicked",
    "interaction": {
      "timestamp": "2024-08-30T10:16:12.124Z",
      "clickId": "d0UtZqE0BZuBPrJS",
      "url": "https://github.com/codeqr-io/codeqr",
      "ip": "63.141.57.109",
      "continent": "NA",
      "country": "US",
      "city": "San Francisco",
      "device": "Desktop",
      "browser": "Chrome",
      "os": "Mac OS",
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36",
      "bot": false,
      "qr": false,
      "referer": "(direct)"
    },
    "link": {
      "id": "cm0faqkyn0001txvfwjfeq7gl",
      "domain": "codeqr.link",
      "key": "79ys3WA",
      "externalId": null,
      "url": "https://github.com/codeqr-io/codeqr",
      "trackConversion": true,
      "archived": false,
      "expiresAt": null,
      "expiredUrl": null,
      "password": null,
      "proxy": false,
      "title": null,
      "description": null,
      "image": null,
      "video": null,
      "rewrite": false,
      "doIndex": false,
      "ios": null,
      "android": null,
      "geo": null,
      "publicStats": false,
      "comments": null,
      "shortLink": "https://codeqr.link/9KUP86d",
      "qrCode": "https://api.codeqr.io/qr?url=https://codeqr.link/9KUP86d?qr=1",
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null,
      "utm_term": null,
      "utm_content": null,
      "userId": "cm022rkcw0000ikt14mscg9sg",
      "projectId": "cm022sis60003ikt1syy7kfhl",
      "clicks": 11,
      "lastClicked": "2024-08-30T07:45:09.000Z",
      "leads": 6,
      "sales": 10,
      "saleAmount": 200000,
      "createdAt": "2024-08-29T13:03:59.098Z",
      "updatedAt": "2024-08-30T10:16:12.126Z"
    }
  }
}

QR Code-level events

Due to the high volume nature of these events, they are scoped to a specific QR code. You need to specify the QR code(s) when creating a webhook.

`qrcode.scanned`

This event is triggered when a user scans a QR code. The event payload contains data.interaction (the scan event, same shape as click event) and data.qrcode (full QR code details).

Sample payload

qrcode.scanned

{
  "id": "evt_b9ywgxWqai2glUpCQjclB17kM",
  "event": "qrcode.scanned",
  "createdAt": "2024-08-30T10:16:13.149Z",
  "data": {
    "eventName": "QR code scanned",
    "interaction": {
      "timestamp": "2024-08-30T10:16:12.124Z",
      "clickId": "d0UtZqE0BZuBPrJS",
      "url": "https://github.com/deusdete/codeqr",
      "ip": "63.141.57.109",
      "continent": "NA",
      "country": "US",
      "city": "San Francisco",
      "device": "Desktop",
      "browser": "Chrome",
      "os": "Mac OS",
      "bot": false,
      "qr": false,
      "referer": "(direct)"
    },
    "qrcode": {
      "id": "cm0pie2xy0007zayvaghkb7d6",
      "domain": "expol.ink",
      "key": "rXUSTPx1tic3-qr",
      "url": "https://app.codeqr.io/",
      "shortLink": "https://expol.ink/rXUSTPx1tic3-qr",
      "scans": 1,
      "projectId": "cm0bfj5eg000045ruzb5o8tar",
      "userId": "clv4ckurp0000nircotd5umkn"
    }
  }
}

Page-level events

Due to the high volume nature of these events, they are scoped to a specific page. You need to specify the page(s) when creating a webhook.

`page.visited`

This event is triggered when a user visits a page. The event payload contains data.interaction (the view event, same shape as click event) and optionally data.page (full page details).

Sample payload

page.visited

{
  "id": "evt_b9ywgxWqai2glUpCQjclB17kM",
  "event": "page.visited",
  "createdAt": "2024-08-30T10:16:13.149Z",
  "data": {
    "eventName": "Page visited",
    "interaction": {
      "timestamp": "2024-08-30T10:16:12.124Z",
      "clickId": "d0UtZqE0BZuBPrJS",
      "url": "https://github.com/deusdete/codeqr",
      "ip": "63.141.57.109",
      "continent": "NA",
      "country": "US",
      "city": "San Francisco",
      "device": "Desktop",
      "browser": "Chrome",
      "os": "Mac OS",
      "bot": false,
      "qr": false,
      "referer": "(direct)"
    },
    "page": {
      "id": "cm0snvcxr002jp80474b2dckg",
      "domain": "expol.ink",
      "key": "p/pHs20VCe8V",
      "name": "Deixe seu feedback",
      "type": "feedback",
      "views": 1,
      "projectId": "cm0bfj5eg000045ruzb5o8tar",
      "userId": "clv4ckurp0000nircotd5umkn"
    }
  }
}

Getting Started

Links

QR Codes

Integrations

Project-level events

`link.created`

`link.updated`

`link.deleted`

`qrcode.created`

`qrcode.updated`

`qrcode.deleted`

`page.created`

`page.updated`

`page.deleted`

`lead.created`

`sale.created`

Payload field: `interaction`

Link-level events

`link.clicked`

QR Code-level events

`qrcode.scanned`

Page-level events

`page.visited`

​Project-level events

​link.created

​link.updated

​link.deleted

​qrcode.created

​qrcode.updated

​qrcode.deleted

​page.created

​page.updated

​page.deleted

​lead.created

​sale.created

​Payload field: interaction

​Link-level events

​link.clicked

​QR Code-level events

​qrcode.scanned

​Page-level events

​page.visited

Project-level events

`link.created`

`link.updated`

`link.deleted`

`qrcode.created`

`qrcode.updated`

`qrcode.deleted`

`page.created`

`page.updated`

`page.deleted`

`lead.created`

`sale.created`

Payload field: `interaction`

Link-level events

`link.clicked`

QR Code-level events

`qrcode.scanned`

Page-level events

`page.visited`