Skip to main content

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.

TopicNeedsSent when
scores/updatedread_productsThe scores of a product, ingredient, packaging or organization were computed
questionnaires/answeredread_questionnairesA questionnaire was answered
app/scopes_updatednoneThe installation's scopes or organizations changed
app/uninstallednoneThe installation was uninstalled
app_subscription/updatednoneThe status of the installation's subscription changed
app_charge/updatednoneThe 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"
}
]
}
FieldTypeMeaning
entity.typeproduct, ingredient, packaging or organizationWhat the scores are about
entity.idintegerIts id
entity.organizationIdinteger or nullThe organization that owns it
scores[].scoreIdintegerThe score
scores[].code, labelstringIts code and display name
scores[].valuenumber or nullThe value, null when it could not be computed
scores[].unitstring or nullThe 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"
}
FieldTypeMeaning
questionnaire.idintegerThe questionnaire
questionnaire.versionIdintegerThe version of the questionnaire that was answered
statusopen or lockedlocked once the answers are validated
updatedAtdate-timeThe 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"
}