# Webhook events

> The payload of every webhook topic, from the JSON Schemas the platform's deliveries follow.

Source: https://developers-staging.foodpilot.tech/reference/webhook-events

Every delivery has the same envelope (`id`, `topic`, `apiVersion`, `occurredAt`, `platform`, `installationId`, `organizationId`, `data`): see [Webhooks](/build/webhooks). Below, the `data` of each topic.

## `app/scopes_updated`

The scopes or the organizations of the installation changed (re-consent or update). No scope needed.

| Field | Always | Value | Meaning |
|---|---|---|---|
| `data.installationId` | Yes | string, uuid |  |
| `data.scopes` | Yes | list of string | The scopes now granted. |
| `data.organizationIds` | Yes | list of integer | The organizations now covered. |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://dev.positive-app.fr/schemas/webhooks/app.scopes_updated.schema.json",
  "title": "app/scopes_updated",
  "description": "The scopes or the organizations of the installation changed (re-consent or update). No scope needed.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "topic",
    "apiVersion",
    "occurredAt",
    "platform",
    "installationId",
    "organizationId",
    "data"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The event id. Identical on every attempt and redelivery of the same event: use it to deduplicate."
    },
    "topic": {
      "const": "app/scopes_updated"
    },
    "apiVersion": {
      "const": "v1"
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the platform queued the delivery (RFC 3339)."
    },
    "platform": {
      "type": "string",
      "minLength": 1,
      "description": "The platform (tenant) the event comes from."
    },
    "installationId": {
      "type": "string",
      "format": "uuid",
      "description": "The installation the event is delivered to."
    },
    "organizationId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The organization the event is about; null for events about the installation itself."
    },
    "data": {
      "type": "object",
      "required": [
        "installationId",
        "scopes",
        "organizationIds"
      ],
      "properties": {
        "installationId": {
          "type": "string",
          "format": "uuid"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The scopes now granted."
        },
        "organizationIds": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "The organizations now covered."
        }
      }
    }
  }
}
```

</details>

## `app/uninstalled`

The installation was uninstalled: this is the last event it receives. No scope needed.

| Field | Always | Value | Meaning |
|---|---|---|---|
| `data.installationId` | Yes | string, uuid |  |
| `data.scopes` | Yes | list of string | The scopes now granted. |
| `data.organizationIds` | Yes | list of integer | The organizations now covered. |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://dev.positive-app.fr/schemas/webhooks/app.uninstalled.schema.json",
  "title": "app/uninstalled",
  "description": "The installation was uninstalled: this is the last event it receives. No scope needed.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "topic",
    "apiVersion",
    "occurredAt",
    "platform",
    "installationId",
    "organizationId",
    "data"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The event id. Identical on every attempt and redelivery of the same event: use it to deduplicate."
    },
    "topic": {
      "const": "app/uninstalled"
    },
    "apiVersion": {
      "const": "v1"
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the platform queued the delivery (RFC 3339)."
    },
    "platform": {
      "type": "string",
      "minLength": 1,
      "description": "The platform (tenant) the event comes from."
    },
    "installationId": {
      "type": "string",
      "format": "uuid",
      "description": "The installation the event is delivered to."
    },
    "organizationId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The organization the event is about; null for events about the installation itself."
    },
    "data": {
      "type": "object",
      "required": [
        "installationId",
        "scopes",
        "organizationIds"
      ],
      "properties": {
        "installationId": {
          "type": "string",
          "format": "uuid"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The scopes now granted."
        },
        "organizationIds": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "The organizations now covered."
        }
      }
    }
  }
}
```

</details>

## `app_charge/updated`

The status of a one-time charge of the installation changed. No scope needed.

| Field | Always | Value | Meaning |
|---|---|---|---|
| `data.installationId` | Yes | string, uuid |  |
| `data.chargeId` | Yes | string |  |
| `data.status` | Yes | string |  |
| `data.planId` | Yes | string |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://dev.positive-app.fr/schemas/webhooks/app_charge.updated.schema.json",
  "title": "app_charge/updated",
  "description": "The status of a one-time charge of the installation changed. No scope needed.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "topic",
    "apiVersion",
    "occurredAt",
    "platform",
    "installationId",
    "organizationId",
    "data"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The event id. Identical on every attempt and redelivery of the same event: use it to deduplicate."
    },
    "topic": {
      "const": "app_charge/updated"
    },
    "apiVersion": {
      "const": "v1"
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the platform queued the delivery (RFC 3339)."
    },
    "platform": {
      "type": "string",
      "minLength": 1,
      "description": "The platform (tenant) the event comes from."
    },
    "installationId": {
      "type": "string",
      "format": "uuid",
      "description": "The installation the event is delivered to."
    },
    "organizationId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The organization the event is about; null for events about the installation itself."
    },
    "data": {
      "type": "object",
      "required": [
        "installationId",
        "chargeId",
        "status",
        "planId"
      ],
      "properties": {
        "installationId": {
          "type": "string",
          "format": "uuid"
        },
        "chargeId": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "planId": {
          "type": "string"
        }
      }
    }
  }
}
```

</details>

## `app_subscription/updated`

The status of the installation's subscription changed. No scope needed.

| Field | Always | Value | Meaning |
|---|---|---|---|
| `data.installationId` | Yes | string, uuid |  |
| `data.subscriptionId` | Yes | string |  |
| `data.status` | Yes | string | The marketplace's status, for instance trialing, active, past_due or canceled. |
| `data.planId` | Yes | string |  |
| `data.currentPeriodEnd` | Yes | string or null, date-time |  |
| `data.cancelAtPeriodEnd` | Yes | boolean |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://dev.positive-app.fr/schemas/webhooks/app_subscription.updated.schema.json",
  "title": "app_subscription/updated",
  "description": "The status of the installation's subscription changed. No scope needed.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "topic",
    "apiVersion",
    "occurredAt",
    "platform",
    "installationId",
    "organizationId",
    "data"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The event id. Identical on every attempt and redelivery of the same event: use it to deduplicate."
    },
    "topic": {
      "const": "app_subscription/updated"
    },
    "apiVersion": {
      "const": "v1"
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the platform queued the delivery (RFC 3339)."
    },
    "platform": {
      "type": "string",
      "minLength": 1,
      "description": "The platform (tenant) the event comes from."
    },
    "installationId": {
      "type": "string",
      "format": "uuid",
      "description": "The installation the event is delivered to."
    },
    "organizationId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The organization the event is about; null for events about the installation itself."
    },
    "data": {
      "type": "object",
      "required": [
        "installationId",
        "subscriptionId",
        "status",
        "planId",
        "currentPeriodEnd",
        "cancelAtPeriodEnd"
      ],
      "properties": {
        "installationId": {
          "type": "string",
          "format": "uuid"
        },
        "subscriptionId": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "description": "The marketplace's status, for instance trialing, active, past_due or canceled."
        },
        "planId": {
          "type": "string"
        },
        "currentPeriodEnd": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "cancelAtPeriodEnd": {
          "type": "boolean"
        }
      }
    }
  }
}
```

</details>

## `questionnaires/answered`

A questionnaire was answered. A summary without the values: read them with GET /api/app/v1/questionnaires/&#123;id&#125;. Needs the read_questionnaires scope and an organization the installation covers.

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://dev.positive-app.fr/schemas/webhooks/questionnaires.answered.schema.json",
  "title": "questionnaires/answered",
  "description": "A questionnaire was answered. A summary without the values: read them with GET /api/app/v1/questionnaires/{id}. Needs the read_questionnaires scope and an organization the installation covers.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "topic",
    "apiVersion",
    "occurredAt",
    "platform",
    "installationId",
    "organizationId",
    "data"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The event id. Identical on every attempt and redelivery of the same event: use it to deduplicate."
    },
    "topic": {
      "const": "questionnaires/answered"
    },
    "apiVersion": {
      "const": "v1"
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the platform queued the delivery (RFC 3339)."
    },
    "platform": {
      "type": "string",
      "minLength": 1,
      "description": "The platform (tenant) the event comes from."
    },
    "installationId": {
      "type": "string",
      "format": "uuid",
      "description": "The installation the event is delivered to."
    },
    "organizationId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The organization the event is about; null for events about the installation itself."
    },
    "data": {
      "$ref": "#/$defs/QuestionnaireAnswers"
    }
  },
  "$defs": {
    "entityType": {
      "enum": [
        "product",
        "ingredient",
        "packaging",
        "organization"
      ]
    },
    "QuestionnaireAnswers": {
      "type": "object",
      "required": [
        "id",
        "questionnaire",
        "entity",
        "status",
        "updatedAt"
      ],
      "properties": {
        "id": {
          "type": "integer"
        },
        "questionnaire": {
          "type": "object",
          "required": [
            "id",
            "versionId"
          ],
          "properties": {
            "id": {
              "type": "integer"
            },
            "versionId": {
              "type": "integer",
              "description": "The identifier of the version of the questionnaire that was answered."
            }
          }
        },
        "entity": {
          "type": "object",
          "required": [
            "type",
            "id"
          ],
          "properties": {
            "type": {
              "$ref": "#/$defs/entityType"
            },
            "id": {
              "type": "integer"
            }
          }
        },
        "status": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "The last time the answers were written."
        }
      }
    }
  }
}
```

</details>

## `scores/updated`

The scores of a product, ingredient, packaging or organization were computed. Needs the read_products scope and an organization the installation covers.

| Field | Always | Value | Meaning |
|---|---|---|---|
| `data.entity` | Yes | object, with `type`, `id`, `organizationId` |  |
| `data.entity.type` | Yes | one of `product`, `ingredient`, `packaging`, `organization` |  |
| `data.entity.id` | Yes | integer |  |
| `data.entity.organizationId` | Yes | integer or null |  |
| `data.scores` | Yes | list of object, with `scoreId`, `code`, `label`, `value`, `unit` |  |

<details>
<summary>JSON Schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://dev.positive-app.fr/schemas/webhooks/scores.updated.schema.json",
  "title": "scores/updated",
  "description": "The scores of a product, ingredient, packaging or organization were computed. Needs the read_products scope and an organization the installation covers.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "topic",
    "apiVersion",
    "occurredAt",
    "platform",
    "installationId",
    "organizationId",
    "data"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The event id. Identical on every attempt and redelivery of the same event: use it to deduplicate."
    },
    "topic": {
      "const": "scores/updated"
    },
    "apiVersion": {
      "const": "v1"
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the platform queued the delivery (RFC 3339)."
    },
    "platform": {
      "type": "string",
      "minLength": 1,
      "description": "The platform (tenant) the event comes from."
    },
    "installationId": {
      "type": "string",
      "format": "uuid",
      "description": "The installation the event is delivered to."
    },
    "organizationId": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The organization the event is about; null for events about the installation itself."
    },
    "data": {
      "type": "object",
      "required": [
        "entity",
        "scores"
      ],
      "properties": {
        "entity": {
          "type": "object",
          "required": [
            "type",
            "id",
            "organizationId"
          ],
          "properties": {
            "type": {
              "$ref": "#/$defs/entityType"
            },
            "id": {
              "type": "integer"
            },
            "organizationId": {
              "type": [
                "integer",
                "null"
              ]
            }
          }
        },
        "scores": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Score"
          }
        }
      }
    }
  },
  "$defs": {
    "entityType": {
      "enum": [
        "product",
        "ingredient",
        "packaging",
        "organization"
      ]
    },
    "Score": {
      "type": "object",
      "required": [
        "scoreId",
        "code",
        "label",
        "value",
        "unit"
      ],
      "properties": {
        "scoreId": {
          "type": "integer"
        },
        "code": {
          "type": [
            "string",
            "null"
          ]
        },
        "label": {
          "type": "string"
        },
        "value": {
          "type": [
            "number",
            "null"
          ]
        },
        "unit": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  }
}
```

</details>
