Tipi di evento
L’envelope
{ id, type, apiVersion, createdAt, workspaceId, actor, data }. id è l’ID dell’evento (evt_…), inviato anche come webhook-id. apiVersion è la versione del payload con cui è stato creato l’endpoint (2026-09-01).
actor dice chi ha causato l’evento: user (una persona nell’app), api_key (con il suo id), staff o system (scansioni, job, controlli di dominio). Un’integrazione che scrive indietro tramite l’API può saltare gli eventi causati dalla sua stessa chiave, evitando i loop.
Nuovi tipi di evento e nuovi campi possono comparire in qualsiasi momento: ignora ciò che non conosci. Un cambiamento che romperebbe un parser esce come nuova apiVersion che gli endpoint esistenti scelgono.
Eventi
code.createdUn codice è stato creato nell’app o tramite l’API. Le esecuzioni in blocco inviano bulk.completed.
code.updatedSono cambiati destinazione, contenuto, nome, design, regole, slug, cartella o dominio.
code.status_changedMesso in pausa, ripreso, oppure disattivato e riattivato da Dotwick.
code.deletedUn codice è stato eliminato; il suo link breve risponde 410.
scan.createdUna persona ha scansionato un codice. Bot e anteprime dei link non vengono mai inviati.
bulk.completedUn’esecuzione in blocco è terminata: un evento per esecuzione, con i suoi conteggi.
export.completedUn’esportazione ZIP è terminata o non è riuscita. Leggi l’esportazione per ottenere un nuovo link di download.
domain.status_changedUn dominio personalizzato è passato a un altro stato (verificato, attivo, non riuscito, rilasciato).
form.submittedQualcuno ha risposto a un modulo ospitato. Contiene le risposte (dati personali).
gs1.recall_changedUn lotto, una variante o un seriale GS1 è stato richiamato, ritirato o ripristinato.
alert.firedÈ scattato un avviso sulle scansioni: una scansione, N scansioni in M minuti o nessuna scansione per D giorni.
webhook.testInviato solo da Invia evento di prova. Non puoi iscriverti.
Payload
Un esempio di ogni evento, così come viene consegnato.
code.created
payload
{ "id": "evt_018f3k2m9q4x7c1v", "type": "code.created", "apiVersion": "2026-09-01", "createdAt": "2026-09-12T14:03:51.000Z", "workspaceId": "ws_8f21ac4e9d0b7c11", "actor": { "kind": "api_key", "userId": "u8Hk2LmN0pQ4rS6tV8wX0yZ2aB4cD6eF", "apiKeyId": "key_4f2a9c1e7b3d5a60" }, "data": { "code": { "id": "qr_8841ce2mxk", "workspaceId": "ws_8f21ac4e9d0b7c11", "name": "Van fleet – unit 14", "type": "url", "dynamic": true, "status": "active", "slug": "Xq7mK2p", "domainId": null, "shortUrl": "https://dotwick.co/Xq7mK2p", "content": { "type": "url", "url": "https://example.com/fleet/van-014" }, "design": { "pattern": "rounded", "eyes": { "frame": "circle", "ball": "circle" }, "colors": { "fg": "#18181B", "bg": "#FFFFFF" } }, "rules": { "routes": [], "expiresAt": null, "scanLimit": null, "inactiveUrl": null, "passwordProtected": false }, "folderId": "fld_8k2m4q7x", "templateId": null, "createdBy": "u8Hk2LmN0pQ4rS6tV8wX0yZ2aB4cD6eF", "createdAt": "2026-09-10T09:41:08.000Z", "updatedAt": "2026-09-10T09:41:08.000Z", "scans": 0 } }}code.updated
payload
{ "id": "evt_028f3k2m9q4x7c1v", "type": "code.updated", "apiVersion": "2026-09-01", "createdAt": "2026-09-12T14:03:51.000Z", "workspaceId": "ws_8f21ac4e9d0b7c11", "actor": { "kind": "user", "userId": "u8Hk2LmN0pQ4rS6tV8wX0yZ2aB4cD6eF", "apiKeyId": null }, "data": { "code": { "id": "qr_8841ce2mxk", "workspaceId": "ws_8f21ac4e9d0b7c11", "name": "Van fleet – unit 14", "type": "url", "dynamic": true, "status": "active", "slug": "Xq7mK2p", "domainId": null, "shortUrl": "https://dotwick.co/Xq7mK2p", "content": { "type": "url", "url": "https://example.com/fleet/van-014-spring" }, "design": { "pattern": "rounded", "eyes": { "frame": "circle", "ball": "circle" }, "colors": { "fg": "#18181B", "bg": "#FFFFFF" } }, "rules": { "routes": [], "expiresAt": null, "scanLimit": null, "inactiveUrl": null, "passwordProtected": false }, "folderId": "fld_8k2m4q7x", "templateId": null, "createdBy": "u8Hk2LmN0pQ4rS6tV8wX0yZ2aB4cD6eF", "createdAt": "2026-09-10T09:41:08.000Z", "updatedAt": "2026-09-12T14:03:51.000Z", "scans": 0 }, "changed": [ "content" ], "previousDestination": "https://example.com/fleet/van-014" }}code.status_changed
payload
{ "id": "evt_038f3k2m9q4x7c1v", "type": "code.status_changed", "apiVersion": "2026-09-01", "createdAt": "2026-09-12T14:03:51.000Z", "workspaceId": "ws_8f21ac4e9d0b7c11", "actor": { "kind": "user", "userId": "u8Hk2LmN0pQ4rS6tV8wX0yZ2aB4cD6eF", "apiKeyId": null }, "data": { "code": { "id": "qr_8841ce2mxk", "workspaceId": "ws_8f21ac4e9d0b7c11", "name": "Van fleet – unit 14", "type": "url", "dynamic": true, "status": "paused", "slug": "Xq7mK2p", "domainId": null, "shortUrl": "https://dotwick.co/Xq7mK2p", "content": { "type": "url", "url": "https://example.com/fleet/van-014" }, "design": { "pattern": "rounded", "eyes": { "frame": "circle", "ball": "circle" }, "colors": { "fg": "#18181B", "bg": "#FFFFFF" } }, "rules": { "routes": [], "expiresAt": null, "scanLimit": null, "inactiveUrl": null, "passwordProtected": false }, "folderId": "fld_8k2m4q7x", "templateId": null, "createdBy": "u8Hk2LmN0pQ4rS6tV8wX0yZ2aB4cD6eF", "createdAt": "2026-09-10T09:41:08.000Z", "updatedAt": "2026-09-12T14:03:51.000Z", "scans": 0 }, "from": "active", "to": "paused", "reason": "user" }}code.deleted
payload
{ "id": "evt_048f3k2m9q4x7c1v", "type": "code.deleted", "apiVersion": "2026-09-01", "createdAt": "2026-09-12T14:03:51.000Z", "workspaceId": "ws_8f21ac4e9d0b7c11", "actor": { "kind": "api_key", "userId": "u8Hk2LmN0pQ4rS6tV8wX0yZ2aB4cD6eF", "apiKeyId": "key_4f2a9c1e7b3d5a60" }, "data": { "codeId": "qr_8841ce2mxk", "name": "Van fleet – unit 14", "slug": "Xq7mK2p", "deletedAt": "2026-09-12T14:03:51.000Z" }}scan.created
payload
{ "id": "evt_058f3k2m9q4x7c1v", "type": "scan.created", "apiVersion": "2026-09-01", "createdAt": "2026-09-12T14:03:51.000Z", "workspaceId": "ws_8f21ac4e9d0b7c11", "actor": { "kind": "system", "userId": null, "apiKeyId": null }, "data": { "ts": "2026-09-12T14:03:51.000Z", "codeId": "qr_8841ce2mxk", "codeName": "Van fleet – unit 14", "country": "US", "city": "Portland", "device": "mobile", "os": "iOS 18", "browser": "Safari 18", "source": "qr", "isBot": false }}bulk.completed
payload
{ "id": "evt_068f3k2m9q4x7c1v", "type": "bulk.completed", "apiVersion": "2026-09-01", "createdAt": "2026-09-12T14:03:51.000Z", "workspaceId": "ws_8f21ac4e9d0b7c11", "actor": { "kind": "system", "userId": null, "apiKeyId": null }, "data": { "bulkImportId": "blk_9f24ab7c3e1d5f80", "status": "partially_succeeded", "total": 50, "created": 47, "failed": 1, "invalid": 2, "canceled": 0, "folderId": "fld_8k2m4q7x", "exportId": "exp_2m7x4k9q1c8v3b6n" }}export.completed
payload
{ "id": "evt_078f3k2m9q4x7c1v", "type": "export.completed", "apiVersion": "2026-09-01", "createdAt": "2026-09-12T14:03:51.000Z", "workspaceId": "ws_8f21ac4e9d0b7c11", "actor": { "kind": "system", "userId": null, "apiKeyId": null }, "data": { "exportId": "exp_2m7x4k9q1c8v3b6n", "status": "succeeded", "counts": { "total": 47, "succeeded": 47, "failed": 0 }, "formats": [ "svg", "pdf" ], "expiresAt": "2026-09-19T14:03:51.000Z", "bulkImportId": "blk_9f24ab7c3e1d5f80" }}domain.status_changed
payload
{ "id": "evt_088f3k2m9q4x7c1v", "type": "domain.status_changed", "apiVersion": "2026-09-01", "createdAt": "2026-09-12T14:03:51.000Z", "workspaceId": "ws_8f21ac4e9d0b7c11", "actor": { "kind": "system", "userId": null, "apiKeyId": null }, "data": { "domainId": "dom_5q8w2e7r4t1y9u3i", "hostname": "qr.example.com", "from": "ssl_issuing", "to": "active" }}form.submitted
payload
{ "id": "evt_098f3k2m9q4x7c1v", "type": "form.submitted", "apiVersion": "2026-09-01", "createdAt": "2026-09-12T14:03:51.000Z", "workspaceId": "ws_8f21ac4e9d0b7c11", "actor": { "kind": "system", "userId": null, "apiKeyId": null }, "data": { "codeName": "Open house – RSVP", "submission": { "id": "fsb_6h3j8k1l4z7x2c5v", "codeId": "qr_8841ce2mxk", "submittedAt": "2026-09-12T14:03:51.000Z", "data": { "name": "Sam Okafor", "email": "sam@example.com", "guests": "2" }, "country": "US" } }}gs1.recall_changed
payload
{ "id": "evt_108f3k2m9q4x7c1v", "type": "gs1.recall_changed", "apiVersion": "2026-09-01", "createdAt": "2026-09-12T14:03:51.000Z", "workspaceId": "ws_8f21ac4e9d0b7c11", "actor": { "kind": "user", "userId": "u8Hk2LmN0pQ4rS6tV8wX0yZ2aB4cD6eF", "apiKeyId": null }, "data": { "codeId": "qr_8841ce2mxk", "gtin14": "09506000134352", "qualifier": { "id": "gsq_4v8n2k7m1x5c9b3q", "codeId": "qr_8841ce2mxk", "key": "10:LOT-42", "level": "batch", "cpv": null, "batch": "LOT-42", "serial": null, "links": [], "defaultLinkType": null, "state": "recalled", "recall": { "title": "Do not use batch LOT-42", "body": "Northwind withdrew this batch after a supplier issue. Return the jar for a full refund.", "date": "2026-09-12", "contact": "recalls@example.com" }, "expiry": "271231", "printed": 5000, "note": null, "stateChangedAt": "2026-09-12T14:03:51.000Z", "createdAt": "2026-09-10T09:41:08.000Z", "updatedAt": "2026-09-12T14:03:51.000Z" }, "from": "clear", "to": "recalled" }}alert.fired
payload
{ "id": "evt_128f3k2m9q4x7c1v", "type": "alert.fired", "apiVersion": "2026-09-01", "createdAt": "2026-09-12T14:03:51.000Z", "workspaceId": "ws_8f21ac4e9d0b7c11", "actor": { "kind": "system", "userId": null, "apiKeyId": null }, "data": { "ruleId": "alr_3d9k2m7q4x8c1v5n", "ruleName": "Spring menu: 50 scans in 10 minutes", "kind": "threshold", "scope": { "kind": "folder", "codeId": null, "folderId": "fld_8k2m4q7x" }, "codeId": null, "codeName": null, "scans": 50, "windowStart": "2026-09-12T13:53:51.000Z", "windowEnd": "2026-09-12T14:03:51.000Z", "firedAt": "2026-09-12T14:03:51.000Z" }}webhook.test
payload
{ "id": "evt_118f3k2m9q4x7c1v", "type": "webhook.test", "apiVersion": "2026-09-01", "createdAt": "2026-09-12T14:03:51.000Z", "workspaceId": "ws_8f21ac4e9d0b7c11", "actor": { "kind": "user", "userId": "u8Hk2LmN0pQ4rS6tV8wX0yZ2aB4cD6eF", "apiKeyId": null }, "data": { "endpointId": "whe_3k8m2q9x7c4v1b6n", "message": "Test event from Dotwick" }}Campi di bulk.completed
Un evento per ogni esecuzione terminata, di qualsiasi dimensione, non un code.created per codice. Porta solo i conteggi: recupera i codici dall’esecuzione.
data.bulkImportIdstringID dell’esecuzione (blk_…).data.status"succeeded" | "partially_succeeded" | "failed" | "canceled"Come è finita l’esecuzione.data.totalnumberElementi nella richiesta (righe di un file).data.creatednumberCodici creati.data.failednumberElementi validi il cui codice non è stato creato durante l’esecuzione: si può riprovare.data.invalidnumberElementi saltati prima dell’avvio dell’esecuzione, per dati errati o mancanti.data.cancelednumberElementi non elaborati perché l’esecuzione è stata annullata.data.folderIdstring | nullCartella in cui sono stati archiviati i codici, o null per la radice dello spazio di lavoro.data.exportIdstring | nullID dell’export ZIP quando l’esecuzione ne ha chiesto uno, altrimenti null.