Event catalog - Awardee API Docs

This is the complete list of events the platform emits. Subscribe to the ones you care about in Settings → Webhooks. Subscribing to a new event has no effect on existing endpoints — each endpoint receives only events it explicitly opted into. Payloads are delivered as the body of a POST, with metadata (event type, delivery id, signature) in headers. See Overview for the delivery shape and Signing for verification.

Webhook payloads use camelCase field names. This differs from the REST API’s snake_case responses — historical and not worth breaking compatibility over. Within each side, the convention is consistent.

Chatbots

`chatbot.created`

Fires when a chatbot is created via dashboard or POST /chatbots.

{
  "chatbotId": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "name": "Support bot",
  "slug": "support-bot",
  "publicSlug": "ax7q9m",
  "status": "draft",
  "pageIds": [],
  "createdAt": "2026-05-23T10:14:33Z",
  "updatedAt": "2026-05-23T10:14:33Z"
}

`chatbot.updated`

Fires on any mutation of a chatbot’s configuration — name, status, system prompt, attached pages, etc.

{
  "chatbotId": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "name": "Support bot",
  "slug": "support-bot",
  "publicSlug": "ax7q9m",
  "status": "active",
  "pageIds": ["2c1b4a9f-7e8d-4a3c-9b1f-6e5d4c3b2a1f"],
  "createdAt": "2026-05-23T10:14:33Z",
  "updatedAt": "2026-05-23T11:02:09Z"
}

`chatbot.deleted`

Fires when a chatbot is hard-deleted.

{
  "chatbotId": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "deletedAt": "2026-05-23T11:14:33Z"
}

Conversations

`conversation.created`

Fires when an end-user starts a new conversation with a chatbot. The bot has been provisioned but no user messages have been sent yet.

{
  "conversation": {
    "id": "3a9d2e8f-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
    "chatbotId": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
    "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
    "status": "bot_active",
    "priority": "medium",
    "resolvedModel": "gpt-4o-mini",
    "qrCodeId": "5d9e8a7c-3b2a-1d0f-9e8f-3a9d2e1b4c4f",
    "productId": null,
    "objectId": null,
    "createdAt": "2026-05-23T10:14:33Z"
  }
}

qrCodeId / productId / objectId reflect the entry surface — null if the conversation didn’t originate from a scan.

`conversation.updated`

Fires when any conversation field changes: status, priority, title, contact info, assignment. Payload includes the new state and a changes object describing the diff.

{
  "conversation": {
    "id": "3a9d2e8f-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
    "chatbotId": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
    "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
    "status": "open",
    "priority": "high",
    "title": "Refund request",
    "contactEmail": "[email protected]",
    "contactName": "Alex Rivera",
    "contactPhone": null,
    "assignedTo": "2c1b4a9f-7e8d-4a3c-9b1f-6e5d4c3b2a1f"
  },
  "changes": {
    "status": { "from": "agent_requested", "to": "open" },
    "priority": { "from": "medium", "to": "high" }
  }
}

`message.created`

Fires for every new message in a conversation — user, assistant, system. System messages include an event field describing what triggered them (status change, human takeover, conversation reopen).

{
  "conversation": {
    "id": "3a9d2e8f-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
    "chatbotId": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
    "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e"
  },
  "message": {
    "id": "7e8d4a3c-9b1f-6e5d-4c3b-2a1f2c1b4a9f",
    "conversationId": "3a9d2e8f-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
    "role": "assistant",
    "source": "human",
    "text": "Refund issued. You'll see it on your statement in 3–5 business days.",
    "agentId": "2c1b4a9f-7e8d-4a3c-9b1f-6e5d4c3b2a1f",
    "createdAt": "2026-05-23T10:18:41Z"
  }
}

role is one of user, assistant, system. For assistant messages, source is "bot", "human", or "api" (when delivered via POST /conversations/{id}/messages). For user messages, source is "email" when the message arrived via inbound email reply, otherwise absent.

Messages with attachments

When the message carries image attachments, message.attachments is included. The field is omitted entirely when there are none — don’t expect an empty array.

{
  "conversation": {
    "id": "3a9d2e8f-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
    "chatbotId": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
    "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e"
  },
  "message": {
    "id": "7e8d4a3c-9b1f-6e5d-4c3b-2a1f2c1b4a9f",
    "conversationId": "3a9d2e8f-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
    "role": "user",
    "text": "Is this damage covered by warranty?",
    "attachments": [
      {
        "assetId": "4527c594-c7e1-488a-8e40-f043197e2ce1",
        "url": "https://files.awardee.dev/orgs/3c1e.../library/d9/d98192a6743e...jpg",
        "mediaType": "image/jpeg",
        "filename": "front-of-box"
      }
    ],
    "createdAt": "2026-05-23T10:18:41Z"
  }
}

attachments[].assetId

string (uuid)

required

Stable identifier for the underlying bytes in the org’s asset library. Re-attaching the same image to a different message returns the same assetId. Treat as opaque.

attachments[].url

string

required

Public URL to fetch the image. Long-lived — content-addressed paths never expire and are immutable.

attachments[].mediaType

string

required

MIME type as detected by Awardee’s pipeline. May differ from the original upload if the asset was re-encoded by the compression step (e.g. image/png → image/webp).

attachments[].filename

string

required

Human-readable filename, used as <img alt> text. May fall back to a generic name (upload, image.png) when the source had no filename (paste from clipboard, inline email image).

URLs are content-addressed within an organization. Attaching the same image bytes to two different messages — even in different conversations — produces the same url and assetId. Don’t dedupe webhook events by attachment URL; use message.id for message-level idempotency.

Submissions

`page.submission.created`

Fires when an end-user submits a form attached to a page.

{
  "submissionId": "9e8a7c3b-2a1d-0f9e-8f3a-9d2e1b4c4f5d",
  "pageId": "4c4f5d9e-8a7c-3b2a-1d0f-9e8f3a9d2e1b",
  "pageTitle": "Warranty registration",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "data": {
    "name": "Alex Rivera",
    "email": "[email protected]",
    "purchase_date": "2026-04-12"
  },
  "metadata": { "userAgent": "Mozilla/5.0 …" },
  "destination": null,
  "qrCodeId": "5d9e8a7c-3b2a-1d0f-9e8f-3a9d2e1b4c4f",
  "productId": null,
  "objectId": null,
  "conversationId": null,
  "viewedAt": "2026-05-23T10:13:51Z",
  "createdAt": "2026-05-23T10:14:33Z"
}

`submission.updated`

Fires on any mutation of a submission — status, priority, flag, assignment, notes.

{
  "submissionId": "9e8a7c3b-2a1d-0f9e-8f3a-9d2e1b4c4f5d",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "pageId": "4c4f5d9e-8a7c-3b2a-1d0f-9e8f3a9d2e1b",
  "submissionNumber": 142,
  "status": "resolved",
  "priority": "medium",
  "flagged": false,
  "assigneeId": "2c1b4a9f-7e8d-4a3c-9b1f-6e5d4c3b2a1f",
  "createdAt": "2026-05-23T10:14:33Z"
}

QR codes

`qr_code.scanned`

Fires on every scan of a tracked QR code, including from misconfigured codes and scans that resolve to “not found”.

{
  "qrCodeId": "5d9e8a7c-3b2a-1d0f-9e8f-3a9d2e1b4c4f",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "name": "Lobby poster Q2",
  "description": "Front-desk poster — Q2 2026 campaign",
  "properties": [
    { "key": "campaign", "value": "q2-2026" },
    { "key": "location", "value": "SF lobby" }
  ],
  "group": {
    "id": "1d0f9e8f-3a9d-2e1b-4c4f-5d9e8a7c3b2a",
    "name": "Q2 campaign"
  },
  "destination": {
    "type": "chatbot",
    "chatbotId": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
    "url": null
  },
  "liveParams": { "utm_source": "poster" },
  "scanMeta": {
    "userAgent": "Mozilla/5.0 …",
    "ipCountry": "US",
    "ipRegion": "CA",
    "referer": null
  },
  "scannedAt": "2026-05-23T10:14:33Z"
}

`qr_code.updated`

Fires on any mutation — destination changes, name, description, properties, URL params, status.

{
  "qrCodeId": "5d9e8a7c-3b2a-1d0f-9e8f-3a9d2e1b4c4f",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "groupId": "1d0f9e8f-3a9d-2e1b-4c4f-5d9e8a7c3b2a",
  "publicSlug": "ax7q9m",
  "name": "Lobby poster Q2",
  "description": "Front-desk poster — Q2 2026 campaign",
  "status": "active",
  "destination": {
    "type": "chatbot",
    "chatbot": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
    "page": null,
    "knowledgeBase": null,
    "url": null
  },
  "totalScans": 142,
  "lastScannedAt": "2026-05-23T09:58:12Z",
  "createdAt": "2026-04-01T10:14:33Z",
  "updatedAt": "2026-05-23T10:14:33Z"
}

QR groups

`qr_group.created` / `qr_group.updated`

{
  "qrGroupId": "1d0f9e8f-3a9d-2e1b-4c4f-5d9e8a7c3b2a",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "name": "Q2 campaign",
  "description": "Codes printed for the Q2 push.",
  "status": "active",
  "destination": {
    "type": "chatbot",
    "chatbot": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
    "page": null,
    "knowledgeBase": null,
    "url": null
  },
  "createdAt": "2026-04-01T10:14:33Z",
  "updatedAt": "2026-05-23T10:14:33Z"
}

A group-level destination is inherited by every child code that doesn’t override it.

`qr_group.deleted`

{
  "qrGroupId": "1d0f9e8f-3a9d-2e1b-4c4f-5d9e8a7c3b2a",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "deletedAt": "2026-05-23T11:14:33Z"
}

Products

`product.scanned`

Fires when a GS1 Digital Link URL resolves to one of your products.

{
  "productId": "8a7c3b2a-1d0f-9e8f-3a9d-2e1b4c4f5d9e",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "name": "Hydration Bottle 750ml",
  "description": "Insulated stainless, 750ml.",
  "gtin": "00614141999996",
  "metadata": { "color": "slate" },
  "properties": [
    { "key": "material", "value": "stainless" }
  ],
  "destination": {
    "type": "chatbot",
    "chatbot": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
    "page": null,
    "knowledgeBase": null,
    "url": null
  },
  "liveParams": { "lot": "L2026-04" },
  "gs1": { "10": "L2026-04", "21": "SN-99182" },
  "scanMeta": {
    "userAgent": "Mozilla/5.0 …",
    "ipCountry": "DE"
  },
  "scannedAt": "2026-05-23T10:14:33Z"
}

`product.created` / `product.updated`

{
  "productId": "8a7c3b2a-1d0f-9e8f-3a9d-2e1b4c4f5d9e",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "name": "Hydration Bottle 750ml",
  "gtin": "00614141999996",
  "status": "active",
  "destination": {
    "type": "chatbot",
    "chatbot": "1b4c4f5d-9e8a-7c3b-2a1d-0f9e8f3a9d2e",
    "page": null,
    "knowledgeBase": null,
    "url": null
  },
  "createdAt": "2026-04-01T10:14:33Z",
  "updatedAt": "2026-05-23T10:14:33Z"
}

`product.deleted`

{
  "productId": "8a7c3b2a-1d0f-9e8f-3a9d-2e1b4c4f5d9e",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "deletedAt": "2026-05-23T11:14:33Z"
}

Objects

Programmable scan URLs that aren’t QR codes or products — custom-typed entities you mint and resolve under /o/<slug>.

`object.scanned`

{
  "objectId": "3b2a1d0f-9e8f-3a9d-2e1b-4c4f5d9e8a7c",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "type": "asset",
  "externalId": "SN-99182",
  "publicSlug": "k3m9pq",
  "name": "Welder #41",
  "description": "Shop floor station 41.",
  "metadata": { "shop": "SF" },
  "properties": [
    { "key": "installed_at", "value": "2025-11-02" }
  ],
  "destination": {
    "type": "page",
    "chatbot": null,
    "page": "4c4f5d9e-8a7c-3b2a-1d0f-9e8f3a9d2e1b",
    "knowledgeBase": null,
    "url": null
  },
  "liveParams": {},
  "urlParams": [],
  "scanMeta": {
    "userAgent": "Mozilla/5.0 …",
    "ipCountry": "US"
  },
  "scannedAt": "2026-05-23T10:14:33Z"
}

`object.created` / `object.updated`

{
  "objectId": "3b2a1d0f-9e8f-3a9d-2e1b-4c4f5d9e8a7c",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "type": "asset",
  "externalId": "SN-99182",
  "publicSlug": "k3m9pq",
  "name": "Welder #41",
  "description": "Shop floor station 41.",
  "metadata": { "shop": "SF" },
  "destination": {
    "type": "page",
    "chatbot": null,
    "page": "4c4f5d9e-8a7c-3b2a-1d0f-9e8f3a9d2e1b",
    "knowledgeBase": null,
    "url": null
  },
  "isActive": true,
  "createdAt": "2026-04-01T10:14:33Z",
  "updatedAt": "2026-05-23T10:14:33Z"
}

`object.deleted`

The slug stays permanently reserved so analytics rows keep their references — it will never be reassigned to a new object.

{
  "objectId": "3b2a1d0f-9e8f-3a9d-2e1b-4c4f5d9e8a7c",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "type": "asset",
  "externalId": "SN-99182",
  "publicSlug": "k3m9pq",
  "deletedAt": "2026-05-23T11:14:33Z"
}

Articles

`article.created` / `article.updated`

{
  "articleId": "2e1b4c4f-5d9e-8a7c-3b2a-1d0f9e8f3a9d",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "knowledgeBaseId": "9d2e1b4c-4f5d-9e8a-7c3b-2a1d0f9e8f3a",
  "categoryId": "f5d9e8a7-c3b2-a1d0-f9e8-f3a9d2e1b4c4",
  "title": "How returns work",
  "slug": "how-returns-work",
  "status": "draft",
  "visibility": "public",
  "language": "en",
  "publishedAt": null,
  "createdAt": "2026-04-01T10:14:33Z",
  "updatedAt": "2026-05-23T10:14:33Z"
}

`article.published`

Fires when an article transitions from draft to published (and on first publish of a translation).

{
  "articleId": "2e1b4c4f-5d9e-8a7c-3b2a-1d0f9e8f3a9d",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "knowledgeBaseId": "9d2e1b4c-4f5d-9e8a-7c3b-2a1d0f9e8f3a",
  "categoryId": "f5d9e8a7-c3b2-a1d0-f9e8-f3a9d2e1b4c4",
  "title": "How returns work",
  "slug": "how-returns-work",
  "status": "published",
  "visibility": "public",
  "language": "en",
  "publishedAt": "2026-05-23T10:14:33Z",
  "createdAt": "2026-04-01T10:14:33Z",
  "updatedAt": "2026-05-23T10:14:33Z"
}

`article.unpublished`

Fires when an article transitions back to draft / unpublished / archived.

{
  "articleId": "2e1b4c4f-5d9e-8a7c-3b2a-1d0f9e8f3a9d",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "status": "unpublished",
  "language": "en",
  "publishedAt": null,
  "updatedAt": "2026-05-23T11:14:33Z"
}

`article.deleted`

{
  "articleId": "2e1b4c4f-5d9e-8a7c-3b2a-1d0f9e8f3a9d",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "deletedAt": "2026-05-23T11:14:33Z"
}

`article.indexed`

Fires when the embedding pipeline finishes writing chunks for an article (primary language + every translation). The article is now retrievable via chatbot search.

{
  "articleId": "2e1b4c4f-5d9e-8a7c-3b2a-1d0f9e8f3a9d",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "language": "en",
  "languages": ["en", "es", "fr"],
  "indexedAt": "2026-05-23T10:14:33Z"
}

language is the article’s primary language; languages lists every language that was embedded in this run (primary + each translation that had content).

`article.indexing_failed`

Fires when the embedding pipeline errors out for an article. indexing_status on the article is set to failed and the error string travels in this payload (it isn’t exposed via the public API).

{
  "articleId": "2e1b4c4f-5d9e-8a7c-3b2a-1d0f9e8f3a9d",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "language": "en",
  "error": "OpenAI API request timed out",
  "failedAt": "2026-05-23T10:14:33Z"
}

Article categories

`article_category.created` / `article_category.updated`

{
  "categoryId": "f5d9e8a7-c3b2-a1d0-f9e8-f3a9d2e1b4c4",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "knowledgeBaseId": "9d2e1b4c-4f5d-9e8a-7c3b-2a1d0f9e8f3a",
  "parentId": null,
  "name": "Shipping & returns",
  "slug": "shipping-returns",
  "createdAt": "2026-04-01T10:14:33Z"
}

`article_category.deleted`

A cascade delete of a non-empty category also emits one article.deleted per child article.

{
  "categoryId": "f5d9e8a7-c3b2-a1d0-f9e8-f3a9d2e1b4c4",
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "deletedAt": "2026-05-23T11:14:33Z"
}

Members

`member.invited`

Fires when an org owner sends an invite.

{
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "orgName": "Acme Inc",
  "email": "[email protected]",
  "invitedByUserId": "2c1b4a9f-7e8d-4a3c-9b1f-6e5d4c3b2a1f",
  "invitedAt": "2026-05-23T10:14:33Z"
}

`member.joined`

Fires when an invited user accepts and is added to the org.

{
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "orgName": "Acme Inc",
  "userId": "9b1f6e5d-4c3b-2a1f-2c1b-4a9f7e8d4a3c",
  "joinedAt": "2026-05-23T10:14:33Z"
}

`member.removed`

Fires when a member is removed from the org, or when the org is deleted (one event per remaining member).

{
  "orgId": "8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e",
  "orgName": "Acme Inc",
  "userId": "9b1f6e5d-4c3b-2a1f-2c1b-4a9f7e8d4a3c",
  "removedByUserId": "2c1b4a9f-7e8d-4a3c-9b1f-6e5d4c3b2a1f",
  "reason": "removed",
  "removedAt": "2026-05-23T10:14:33Z"
}

reason is one of "removed", "org_deleted", "left".

​Chatbots

​chatbot.created

​chatbot.updated

​chatbot.deleted

​Conversations

​conversation.created

​conversation.updated

​message.created

​Messages with attachments

​Submissions

​page.submission.created

​submission.updated

​QR codes

​qr_code.scanned

​qr_code.updated

​QR groups

​qr_group.created / qr_group.updated

​qr_group.deleted

​Products

​product.scanned

​product.created / product.updated

​product.deleted

​Objects

​object.scanned

​object.created / object.updated

​object.deleted

​Articles

​article.created / article.updated

​article.published

​article.unpublished

​article.deleted

​article.indexed

​article.indexing_failed

​Article categories

​article_category.created / article_category.updated

​article_category.deleted

​Members

​member.invited

​member.joined

​member.removed

Chatbots

`chatbot.created`

`chatbot.updated`

`chatbot.deleted`

Conversations

`conversation.created`

`conversation.updated`

`message.created`

Messages with attachments

Submissions

`page.submission.created`

`submission.updated`

QR codes

`qr_code.scanned`

`qr_code.updated`

QR groups

`qr_group.created` / `qr_group.updated`

`qr_group.deleted`

Products

`product.scanned`

`product.created` / `product.updated`

`product.deleted`

Objects

`object.scanned`

`object.created` / `object.updated`

`object.deleted`

Articles

`article.created` / `article.updated`

`article.published`

`article.unpublished`

`article.deleted`

`article.indexed`

`article.indexing_failed`

Article categories

`article_category.created` / `article_category.updated`

`article_category.deleted`

Members

`member.invited`

`member.joined`

`member.removed`