Webhook events
Every delivery has the same envelope (id, topic, apiVersion, occurredAt, platform, installationId, organizationId, data): see 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. |
JSON Schema
{
"$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."
}
}
}
}
}
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. |
JSON Schema
{
"$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."
}
}
}
}
}
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 |
JSON Schema
{
"$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"
}
}
}
}
}
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 |
JSON Schema
{
"$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"
}
}
}
}
}
questionnaires/answered
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.
JSON Schema
{
"$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."
}
}
}
}
}
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 |
JSON Schema
{
"$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"
]
}
}
}
}
}