# Topics

> The six webhook topics of version 1, the scope each needs, and the data each one carries.

Source: https://developers-staging.foodpilot.tech/build/webhooks/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](/build/webhooks).

| Topic | Needs | Sent when |
|---|---|---|
| [`scores/updated`](#scoresupdated) | `read_products` | The scores of a product, ingredient, packaging or organization were computed |
| [`questionnaires/answered`](#questionnairesanswered) | `read_questionnaires` | A questionnaire was answered |
| [`app/scopes_updated`](#appscopes_updated) | none | The installation's scopes or organizations changed |
| [`app/uninstalled`](#appuninstalled) | none | The installation was uninstalled |
| [`app_subscription/updated`](#app_subscriptionupdated) | none | The status of the installation's subscription changed |
| [`app_charge/updated`](#app_chargeupdated) | 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`.

```json
{
  "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}`.

```json
{
  "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.

```json
{
  "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

```json
{
  "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](/build/billing).

## app_charge/updated

```json
{
  "installationId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "chargeId": "ch_01HZ",
  "status": "paid",
  "planId": "plan_setup"
}
```
