Topics
In this page you will find, for each topic, when it is sent, which scope it needs and what its data holds. The envelope around data is the same for all: see Webhooks.
| Topic | Needs | Sent when |
|---|---|---|
scores/updated | read_products | The scores of a product, ingredient, packaging or organization were computed |
questionnaires/answered | read_questionnaires | A questionnaire was answered |
app/scopes_updated | none | The installation's scopes or organizations changed |
app/uninstalled | none | The installation was uninstalled |
app_subscription/updated | none | The status of the installation's subscription changed |
app_charge/updated | none | The status of a one-time charge changed |
An event about data is delivered only if the event's organization is one the installation covers. The lifecycle and billing topics are always delivered to an active installation. A suspended installation receives nothing.
scores/updated
data holds the entity and its scores. The Score is the same object as in GET /api/app/v1/products/{id}/scores.
{
"entity": { "type": "product", "id": 345, "organizationId": 12 },
"scores": [
{
"scoreId": 3,
"code": "climate_change",
"label": "Climate change",
"value": 1.52,
"unit": "kg CO2 eq"
}
]
}
| Field | Type | Meaning |
|---|---|---|
entity.type | product, ingredient, packaging or organization | What the scores are about |
entity.id | integer | Its id |
entity.organizationId | integer or null | The organization that owns it |
scores[].scoreId | integer | The score |
scores[].code, label | string | Its code and display name |
scores[].value | number or null | The value, null when it could not be computed |
scores[].unit | string or null | The unit |
questionnaires/answered
data is a summary of the answers, a QuestionnaireAnswers without its values. Read the values with GET /api/app/v1/questionnaires/{id}.
{
"id": 88,
"questionnaire": { "id": 4, "versionId": 9 },
"entity": { "type": "product", "id": 345 },
"status": "locked",
"updatedAt": "2026-11-14T10:00:00+01:00"
}
| Field | Type | Meaning |
|---|---|---|
questionnaire.id | integer | The questionnaire |
questionnaire.versionId | integer | The version of the questionnaire that was answered |
status | open or locked | locked once the answers are validated |
updatedAt | date-time | The last time the answers were written |
app/scopes_updated
data lists what the installation holds now. Replace what you recorded.
{
"installationId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"scopes": ["read_products", "read_organizations"],
"organizationIds": [12]
}
app/uninstalled
The same data as app/scopes_updated. It is the last event of the installation: forget its tokens and its secret. Your tokens already answer 401.
app_subscription/updated
{
"installationId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"subscriptionId": "sub_01HZ",
"status": "active",
"planId": "plan_pro",
"currentPeriodEnd": "2026-12-14T10:00:00+00:00",
"cancelAtPeriodEnd": false
}
status is the marketplace's: trialing, active, past_due, canceled, and the states before the customer confirms (pending, declined, expired). currentPeriodEnd is null until a period starts. The platform does not freeze an unpaid app: your app decides what a status means for its own access. See Billing.
app_charge/updated
{
"installationId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"chargeId": "ch_01HZ",
"status": "paid",
"planId": "plan_setup"
}