Skip to main content

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.

FieldAlwaysValueMeaning
data.installationIdYesstring, uuid
data.scopesYeslist of stringThe scopes now granted.
data.organizationIdsYeslist of integerThe 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.

FieldAlwaysValueMeaning
data.installationIdYesstring, uuid
data.scopesYeslist of stringThe scopes now granted.
data.organizationIdsYeslist of integerThe 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.

FieldAlwaysValueMeaning
data.installationIdYesstring, uuid
data.chargeIdYesstring
data.statusYesstring
data.planIdYesstring
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.

FieldAlwaysValueMeaning
data.installationIdYesstring, uuid
data.subscriptionIdYesstring
data.statusYesstringThe marketplace's status, for instance trialing, active, past_due or canceled.
data.planIdYesstring
data.currentPeriodEndYesstring or null, date-time
data.cancelAtPeriodEndYesboolean
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.

FieldAlwaysValueMeaning
data.entityYesobject, with type, id, organizationId
data.entity.typeYesone of product, ingredient, packaging, organization
data.entity.idYesinteger
data.entity.organizationIdYesinteger or null
data.scoresYeslist 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"
]
}
}
}
}
}