> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codeqr.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Event types
> List of available webhook events you can listen to along with their payload examples
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:
```json webhook-payload.json theme={null}
{
"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**](#project-level-events)
* [**Link-level events**](#link-level-events)
* [**QR Code-level events**](#qr-code-level-events)
* [**Page-level events**](#page-level-events)
## Project-level events
These events are triggered in the context of your entire project:
* [`link.created`](#link-created)
* [`link.updated`](#link-updated)
* [`link.deleted`](#link-deleted)
* [`qrcode.created`](#qrcode-created)
* [`qrcode.updated`](#qrcode-updated)
* [`qrcode.deleted`](#qrcode-deleted)
* [`page.created`](#page-created)
* [`page.updated`](#page-updated)
* [`page.deleted`](#page-deleted)
* [`lead.created`](#lead-created)
* [`sale.created`](#sale-created)
* [`partner.enrolled`](#partner-enrolled)
### `link.created`
This event is triggered when a [new link is created](/api-reference/endpoint/create-a-link) in your CodeQR project. The event payload contains the created link's details.
Here's an example payload:
```json link.created theme={null}
{
"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](/api-reference/endpoint/update-a-link) in your CodeQR project. The event payload contains the updated link's details.
Here's an example payload:
```json link.updated theme={null}
{
"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](/api-reference/endpoint/delete-a-link) in your CodeQR project. The event payload contains the deleted link's details.
Here's an example payload:
```json link.deleted theme={null}
{
"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`).
```json qrcode.created theme={null}
{
"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`).
```json page.created theme={null}
{
"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](/api-reference/endpoint/track-lead) via [CodeQR Conversions](/conversions/quickstart). 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:
```json lead.created theme={null}
{
"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](/api-reference/endpoint/track-sale) via [CodeQR Conversions](/conversions/quickstart). 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:
```json sale.created theme={null}
{
"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",
"paymentProcessor": "stripe",
"invoiceId": null
}
}
}
```
### `partner.enrolled`
This event is triggered when a [new partner is enrolled](/api-reference/endpoint/create-a-partner) in your partner program. The event payload contains the following:
* `partner`: Details about the partner that was enrolled.
* `links`: An array of referral links.
Here's an example payload:
```json partner.enrolled theme={null}
{
"id": "evt_ovabfqva8oqZzmLPN1JnwIfdt",
"event": "partner.enrolled",
"createdAt": "2025-04-08T17:11:56.492Z",
"data": {
"id": "pn_1JRB6678XHGBZE95R5PH5QVGS",
"name": "Asleep Pink Mammal",
"email": "chosen.blush.barracuda@codeqr-internal-test.com",
"image": null,
"description": null,
"country": null,
"payoutsEnabledAt": null,
"createdAt": "2025-04-08T17:11:56.446Z",
"status": "approved",
"programId": "prog_CYCu7IMAapjkRpTnr8F1azjN",
"tenantId": null,
"links": [
{
"id": "link_1JRB6677YXQB49RC1HKH7TPJE",
"domain": "codeqr.link",
"key": "uvYO5pMIpctKdUVJlL3jIL4o",
"shortLink": "https://codeqr.link/9KUP86d",
"url": "https://codeqr.io",
"clicks": 0,
"leads": 0,
"sales": 0,
"saleAmount": 0
}
],
"clicks": 0,
"leads": 0,
"sales": 0,
"saleAmount": 0,
"earnings": 0,
"applicationId": 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:
```json link.clicked theme={null}
{
"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).
```json qrcode.scanned theme={null}
{
"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).
```json page.visited theme={null}
{
"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"
}
}
}
```