Este artículo aún no está disponible en español; se muestra a continuación en inglés.
On this pageThe envelope
9 event types, plus ping for testing. Subscribe an endpoint to the ones you need (an empty list means all of them) with POST /webhooks; to verify signatures and handle retries, see Webhooks.
The envelope
Every delivery is a POST with a JSON body of the same four properties: id (stable across retries — de-duplicate on it), type, created_at and data, which is what the sections below describe. The event type and id are repeated in headers, and DPP-Signature signs the raw body. Answer with any 2xx within 10 seconds; otherwise the delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours.
Request headers
POST /your/webhook/path HTTP/1.1Content-Type: application/jsonUser-Agent: Collecta-DPP-Webhooks/1.0DPP-Event: passport.publishedDPP-Event-Id: evt_2f9e8d7c6b5a49382716f5e4d3c2b1a0DPP-Delivery: cm1qc2d3e0030l70fa9b8c7d6DPP-Signature: t=1799920931,v1=5c1f0a…model.created
A battery model was created
Fires once when a model is created, over the API or in the app.
Sent byPOST
/models| data field | Type | Description |
|---|---|---|
| model.id | string | The model id. |
| model.name | string | The model name. |
| model.category | string | EV, LMT or INDUSTRIAL. |
| model.capacityKwh | number | Capacity in kWh. |
| model.chemistry | string | null | Cell chemistry. |
| model.updatedAt | string | When the model last changed (ISO 8601). |
model.created · sample delivery
{"id": "evt_4f0c2b9e8a1d4c7fb3e5a6d7c8b9a0e1","type": "model.created","created_at": "2027-01-15T09:12:44.512Z","data": {"model": {"id": "cm1q8x2k40003l70f9a8s7d6e","name": "Cargo 48V 15Ah","category": "LMT","capacityKwh": 0.72,"chemistry": "Lithium-ion NMC","updatedAt": "2027-01-15T09:12:44.120Z"}}}model.updated
A battery model changed
Fires when a model’s name, chemistry or fields are updated. The payload carries the model’s identity, not the changed fields — read the model to see them.
Sent byPATCH
/models/{id}| data field | Type | Description |
|---|---|---|
| model.id | string | The model id. |
| model.name | string | The model name. |
| model.category | string | EV, LMT or INDUSTRIAL. |
| model.capacityKwh | number | Capacity in kWh. |
| model.chemistry | string | null | Cell chemistry. |
| model.updatedAt | string | When the model last changed (ISO 8601). |
model.updated · sample delivery
{"id": "evt_9a3d1f7c2e5b4a8d9c0b1e2f3a4b5c6d","type": "model.updated","created_at": "2027-02-03T14:20:05.902Z","data": {"model": {"id": "cm1q8x2k40003l70f9a8s7d6e","name": "Cargo 48V 15Ah","category": "LMT","capacityKwh": 0.72,"chemistry": "Lithium-ion NMC","updatedAt": "2027-02-03T14:20:05.511Z"}}}document.uploaded
A document was attached to a model
Fires when a document such as the EU Declaration of Conformity is uploaded.
Sent byPOST
/models/{id}/documents| data field | Type | Description |
|---|---|---|
| document.id | string | The document id. |
| document.modelId | string | The model it belongs to. |
| document.name | string | The document name. |
| document.type | string | The document type, e.g. EU Declaration of Conformity. |
| document.point | integer | Annex XIII point: 1 public, 3 authorities only. |
| document.createdAt | string | Upload time (ISO 8601). |
document.uploaded · sample delivery
{"id": "evt_1b2c3d4e5f60718293a4b5c6d7e8f901","type": "document.uploaded","created_at": "2027-01-15T09:40:12.688Z","data": {"document": {"id": "cm1q9a3fz0011l70fk8m2n4p6","modelId": "cm1q8x2k40003l70f9a8s7d6e","name": "EU Declaration of Conformity — Cargo 48V.pdf","type": "EU Declaration of Conformity","point": 1,"createdAt": "2027-01-15T09:40:12.300Z"}}}passport.created
A battery and its passport were created
Fires once per battery: creating a battery issues its passport as a draft. A batch of 500 sends 500 events.
| data field | Type | Description |
|---|---|---|
| passport.id | string | The passport id. |
| passport.uniqueIdentifier | string | The battery’s unique identifier — the key the QR code resolves. |
| passport.serialNumber | string | null | Your serial number, if you sent one. |
| passport.itemId | string | The battery (item) id. |
| passport.modelId | string | The battery model id. |
| passport.status | string | ORIGINAL, REPURPOSED, REUSED, REMANUFACTURED or WASTE. |
| passport.lifecycleState | string | ACTIVE, or CEASED_RECYCLED once recycled. |
| passport.publishedAt | string | null | When it was first published (ISO 8601); null for a draft. |
| passport.publicUrl | string | null | The resolver URL the QR code encodes. |
A battery brought over with its own uniqueIdentifier on a plan that can publish goes live at once, so publishedAt can already be set.
passport.created · sample delivery
{"id": "evt_7e6d5c4b3a2918f7e6d5c4b3a2918f7e","type": "passport.created","created_at": "2027-01-15T09:58:30.140Z","data": {"passport": {"id": "cm1q8y0bq0006l70fx9y8z7w6","uniqueIdentifier": "C-7KQ2M9XHT4R","serialNumber": "C48-2027-0001","itemId": "cm1q8y0bq0005l70fq2r3t4u5","modelId": "cm1q8x2k40003l70f9a8s7d6e","status": "ORIGINAL","lifecycleState": "ACTIVE","publishedAt": null,"publicUrl": "https://dppapi-production.up.railway.app/p/C-7KQ2M9XHT4R"}}}passport.published
A passport went live
Fires when a draft is published and starts resolving publicly. Publishing an already published passport sends nothing.
| data field | Type | Description |
|---|---|---|
| passport.id | string | The passport id. |
| passport.uniqueIdentifier | string | The battery’s unique identifier — the key the QR code resolves. |
| passport.serialNumber | string | null | Your serial number, if you sent one. |
| passport.itemId | string | The battery (item) id. |
| passport.modelId | string | The battery model id. |
| passport.status | string | ORIGINAL, REPURPOSED, REUSED, REMANUFACTURED or WASTE. |
| passport.lifecycleState | string | ACTIVE, or CEASED_RECYCLED once recycled. |
| passport.publishedAt | string | null | When it was first published (ISO 8601); null for a draft. |
| passport.publicUrl | string | null | The resolver URL the QR code encodes. |
passport.published · sample delivery
{"id": "evt_2f9e8d7c6b5a49382716f5e4d3c2b1a0","type": "passport.published","created_at": "2027-01-15T10:02:11.371Z","data": {"passport": {"id": "cm1q8y0bq0006l70fx9y8z7w6","uniqueIdentifier": "C-7KQ2M9XHT4R","serialNumber": "C48-2027-0001","itemId": "cm1q8y0bq0005l70fq2r3t4u5","modelId": "cm1q8x2k40003l70f9a8s7d6e","status": "ORIGINAL","lifecycleState": "ACTIVE","publishedAt": "2027-01-15T10:02:11.000Z","publicUrl": "https://dppapi-production.up.railway.app/p/C-7KQ2M9XHT4R"}}}passport.status_changed
A passport’s status changed
Fires on a status change. Repurposing, re-use and remanufacturing fork a new, linked passport (Art. 77(7)); the event then names the successor in forked.
Sent byPATCH
/passports/{id}/status| data field | Type | Description |
|---|---|---|
| passport.id | string | The passport id. |
| passport.uniqueIdentifier | string | The battery’s unique identifier — the key the QR code resolves. |
| passport.serialNumber | string | null | Your serial number, if you sent one. |
| passport.itemId | string | The battery (item) id. |
| passport.modelId | string | The battery model id. |
| passport.status | string | ORIGINAL, REPURPOSED, REUSED, REMANUFACTURED or WASTE. |
| passport.lifecycleState | string | ACTIVE, or CEASED_RECYCLED once recycled. |
| passport.publishedAt | string | null | When it was first published (ISO 8601); null for a draft. |
| passport.publicUrl | string | null | The resolver URL the QR code encodes. |
| status | string | The status that was requested. |
| forked.passportId | string | Only on a fork: the successor passport id. |
| forked.uniqueIdentifier | string | Only on a fork: the successor’s identifier. |
passport.status_changed · sample delivery
{"id": "evt_5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d","type": "passport.status_changed","created_at": "2031-05-20T08:15:42.019Z","data": {"passport": {"id": "cm1q8y0bq0006l70fx9y8z7w6","uniqueIdentifier": "C-7KQ2M9XHT4R","serialNumber": "C48-2027-0001","itemId": "cm1q8y0bq0005l70fq2r3t4u5","modelId": "cm1q8x2k40003l70f9a8s7d6e","status": "ORIGINAL","lifecycleState": "ACTIVE","publishedAt": "2027-01-15T10:02:11.000Z","publicUrl": "https://dppapi-production.up.railway.app/p/C-7KQ2M9XHT4R"},"status": "REPURPOSED","forked": {"passportId": "cm2a1k9pz0042l70fh6j7k8l9","uniqueIdentifier": "C-9RW3T6PNC2D"}}}passport.recycled
A battery was recycled
Fires when a passport is marked recycled. The passport ceases (Art. 77(8)) and the resolver answers 410 from then on.
Sent byPOST
/passports/{id}/recycle| data field | Type | Description |
|---|---|---|
| passport.id | string | The passport id. |
| passport.uniqueIdentifier | string | The battery’s unique identifier — the key the QR code resolves. |
| passport.serialNumber | string | null | Your serial number, if you sent one. |
| passport.itemId | string | The battery (item) id. |
| passport.modelId | string | The battery model id. |
| passport.status | string | ORIGINAL, REPURPOSED, REUSED, REMANUFACTURED or WASTE. |
| passport.lifecycleState | string | ACTIVE, or CEASED_RECYCLED once recycled. |
| passport.publishedAt | string | null | When it was first published (ISO 8601); null for a draft. |
| passport.publicUrl | string | null | The resolver URL the QR code encodes. |
passport.recycled · sample delivery
{"id": "evt_8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a39","type": "passport.recycled","created_at": "2037-03-02T11:47:09.233Z","data": {"passport": {"id": "cm1q8y0bq0006l70fx9y8z7w6","uniqueIdentifier": "C-7KQ2M9XHT4R","serialNumber": "C48-2027-0001","itemId": "cm1q8y0bq0005l70fq2r3t4u5","modelId": "cm1q8x2k40003l70f9a8s7d6e","status": "WASTE","lifecycleState": "CEASED_RECYCLED","publishedAt": "2027-01-15T10:02:11.000Z","publicUrl": "https://dppapi-production.up.railway.app/p/C-7KQ2M9XHT4R"}}}passport.event_recorded
Dynamic data was recorded
Fires for every dynamic-data event appended to a passport: state of health, cycles, throughput, temperatures, negative events.
Sent byPOST
/passports/{id}/events| data field | Type | Description |
|---|---|---|
| passport.id | string | The passport id. |
| passport.uniqueIdentifier | string | The battery’s unique identifier — the key the QR code resolves. |
| passport.serialNumber | string | null | Your serial number, if you sent one. |
| passport.itemId | string | The battery (item) id. |
| passport.modelId | string | The battery model id. |
| passport.status | string | ORIGINAL, REPURPOSED, REUSED, REMANUFACTURED or WASTE. |
| passport.lifecycleState | string | ACTIVE, or CEASED_RECYCLED once recycled. |
| passport.publishedAt | string | null | When it was first published (ISO 8601); null for a draft. |
| passport.publicUrl | string | null | The resolver URL the QR code encodes. |
| event.id | string | The event id. |
| event.eventType | string | e.g. SOH_READING, CYCLE_COUNT, OPERATING_CONDITION. |
| event.payload | object | The values recorded, keyed by field name. |
| event.recordedAt | string | When it was recorded (ISO 8601). |
passport.event_recorded · sample delivery
{"id": "evt_3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b","type": "passport.event_recorded","created_at": "2027-06-01T06:00:00.418Z","data": {"passport": {"id": "cm1q8y0bq0006l70fx9y8z7w6","uniqueIdentifier": "C-7KQ2M9XHT4R","serialNumber": "C48-2027-0001","itemId": "cm1q8y0bq0005l70fq2r3t4u5","modelId": "cm1q8x2k40003l70f9a8s7d6e","status": "ORIGINAL","lifecycleState": "ACTIVE","publishedAt": "2027-01-15T10:02:11.000Z","publicUrl": "https://dppapi-production.up.railway.app/p/C-7KQ2M9XHT4R"},"event": {"id": "cm2b4n7qr0051l70fa1b2c3d4","eventType": "SOH_READING","payload": {"stateOfCertifiedEnergy": 97.4,"capacityFade": 2.6},"recordedAt": "2027-06-01T06:00:00.000Z"}}}supplier.submitted
A supplier answered a data request
Fires when a supplier submits values or uploads a file through the link you sent them. request.kind says which; values carry fields, files carry file.
Sent byThe supplier’s form (no API call of yours)
| data field | Type | Description |
|---|---|---|
| request.id | string | The supplier request (upload link) id. |
| request.supplierName | string | null | The supplier, as you named them. |
| request.modelId | string | null | The model the request is for. |
| request.kind | string | values or file. |
| fields | string[] | Only for values: the field names submitted. |
| file.id / filename / mimeType / size | object | Only for file: the uploaded file. |
supplier.submitted · sample delivery
{"id": "evt_6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c","type": "supplier.submitted","created_at": "2027-01-12T16:31:57.770Z","data": {"request": {"id": "cm2c8s1tu0063l70fe5f6g7h8","supplierName": "Cellwerk AG","modelId": "cm1q8x2k40003l70f9a8s7d6e","kind": "values"},"fields": ["criticalRawMaterials","hazardousSubstances"]}}ping
A test delivery
Sent only when you ask for it, to check that an endpoint receives and verifies deliveries. The answer is returned to the caller as the delivery record.
Sent byPOST
/webhooks/{id}/test| data field | Type | Description |
|---|---|---|
| message | string | A fixed explanation of the test. |
The id of a test event starts with evt_test_.
ping · sample delivery
{"id": "evt_test_mg8k2x4p","type": "ping","created_at": "2027-01-10T12:00:00.000Z","data": {"message": "Test event from Collecta DPP. Verify the DPP-Signature header and answer 2xx."}}