React when scores change
In this tutorial you will keep your own copy of the scores of products up to date: the platform calls you when scores are computed, and you store what changed.
1. Subscribe
Add the topic to your manifest. It needs read_products, and you only receive events about the organizations your installation covers:
{
"scopes": ["read_products", "read_organizations"],
"webhooks": [
{ "topic": "scores/updated", "uri": "https://app.example.com/webhooks" },
{ "topic": "app/uninstalled", "uri": "https://app.example.com/webhooks" }
]
}
2. What you receive
The webhook events reference has the full schema. The part you use:
{
"id": "evt_…",
"topic": "scores/updated",
"apiVersion": "v1",
"installationId": "…",
"organizationId": 12,
"data": {
"entity": { "type": "product", "id": 345, "organizationId": 12 },
"scores": [
{ "scoreId": 7, "code": "…", "label": "…", "value": 1.23, "unit": "…" }
]
}
}
entity.type is product, ingredient, packaging or organization. A score's value can be null.
3. Handle the delivery
Verify the signature on the raw body, drop an event id you have already handled, answer quickly, then do the work:
import express from 'express';
app.post('/webhooks', express.raw({ type: () => true, limit: '256kb' }), async (request, response) => {
const installation = installations.get(request.get('x-positive-platform') ?? '');
if (!installation) return response.status(401).json({ error: 'unknown_installation' });
// isValidSignature: see Verify signatures. Try the previous secret too during a rotation.
if (!isValidSignature(request.body, request.get('x-positive-timestamp'), request.get('x-positive-signature-v2'), installation.webhookSecret)) {
return response.status(401).json({ error: 'bad_signature' });
}
const event = JSON.parse(request.body.toString('utf8'));
if (event.topic !== request.get('x-positive-topic') || event.apiVersion !== 'v1') {
return response.status(400).json({ error: 'invalid_envelope' });
}
// A retry or a redelivery carries the same id: acknowledge it, do nothing.
if (!(await events.claim(installation.id, event.id))) return response.json({ status: 'duplicate' });
response.json({ status: 'ok' });
if (event.topic === 'scores/updated') await queue.push(() => saveScores(installation, event.data));
if (event.topic === 'app/uninstalled') await forget(installation);
});
The platform waits 5 seconds at most and counts only a 2xx as delivered: answer first, work afterwards. A delivery that fails is retried, up to 8 attempts over about 45 hours, with the same event id.
4. Store the scores
async function saveScores(installation, data) {
const { type, id } = data.entity;
for (const score of data.scores) {
await db.upsert('scores', {
installationId: installation.id,
entityType: type,
entityId: id,
scoreId: score.scoreId,
value: score.value,
unit: score.unit,
});
}
}
Events can arrive out of order. When the latest state matters, read it from the App API: GET /api/app/v1/products/{id}/scores gives the current scores of a product.
Next
- Verify signatures: the check, in Node.js and Python.
- Topics: the other events.