Webhookok
Az események, amelyeket a Poltura a szerveredre küld; a témakörök, azok adatai, az Ed25519-aláírás, az ellenőrzés menete és az újrapróbálkozási ütemezés.
Ezen az oldalon
A webhook egy aláírt POST kérés a Polturától a szerveredre, amikor történik valami egy olyan boltban, amelyre telepítették
az appodat: leadnak egy rendelést, módosul egy termék, frissítik vagy eltávolítják az appot. A témakörökre a manifest
webhooks mezőjében iratkozhatsz fel, legfeljebb 16-ra, mindegyikhez saját HTTPS-célcímet megadva.
A kézbesítés legalább egyszeri (at-least-once): ugyanaz az esemény kétszer is megérkezhet, ezért tárold el a feldolgozott
események eventId azonosítóját, és hagyd figyelmen kívül az ismétléseket. A body az esemény tárolt JSON-ja, bájtról bájtra;
ellenőrizd az értelmezése előtt, és utasítsd el a 256 KiB-nál nagyobb bodykat.
Témakörök
Egy témakör eseményei csak addig érkeznek meg, amíg a telepítés rendelkezik a mellette feltüntetett jogosultsággal. Az app.* lifecycle eventekhez nem szükséges jogosultság:
| Témakör | Jogosultság | data |
|---|---|---|
product.created | products.read | ProductEventData { productId, handle, title, status, variants? } (variants max 100) |
product.updated | products.read | ugyanaz |
product.deleted | products.read | { productId } |
order.created | orders.read | OrderEventData { orderId, orderNumber, status, paymentStatus, fulfillmentStatus, currency, total, customerId } |
order.updated | orders.read | ugyanaz |
order.paid | orders.read | ugyanaz |
order.fulfilled | orders.read | ugyanaz |
order.cancelled | orders.read | ugyanaz |
customer.created | customers.read | { customerId, email } |
customer.updated | customers.read | ugyanaz |
inventory.updated | products.read | { inventoryItemId, variantId, locationId, available } |
app.installed | nincs | InstallationLifecycleEventData |
app.updated | nincs | ugyanaz |
app.suspended | nincs | ugyanaz |
app.uninstalled | nincs | ugyanaz |
Minden esemény ugyanazt az envelope-ot használja: { eventId, topic, apiVersion: 'v1', occurredAt, storeId, installationId, resourceVersion, data }. A termékek status értéke draft, published vagy archived. Ha egy termékesemény nem tartalmaz variants mezőt, akkor nincs változatlista; a [] azt jelenti, hogy a terméknek nincsenek változatai. Az app.installed akkor érkezik meg, amikor a telepítés már elkészült, nem pedig az előkészítése közben.
Aláírás
A Poltura a <unix seconds>.<raw body> értéket írja alá az Ed25519-kulcsával – ugyanazzal a kulccsal, amellyel a műveleteket is aláírja. Az aláírás 64 bájtos, és v1 verzióként érkezik. A headerek:
| Header | Jelentés |
|---|---|
poltura-timestamp | Unix másodperc, amikor a Poltura aláírta. A 300 másodpercnél nagyobb eltérésű kéréseket a Poltura elutasítja |
poltura-key-id | A platform melyik kulcsa írta alá: betűk, számok, ., _ és -, legfeljebb 64 karakter |
poltura-signature | v1= és maga az aláírás, base64url formátumban, kitöltés (padding) nélkül |
poltura-event-id | Ha jelen van, meg kell egyeznie a bodyban lévő eventId értékével |
poltura-topic | Ha jelen van, meg kell egyeznie a bodyban lévő topic értékével |
poltura-delivery-id | Az adott kézbesítési kísérlet azonosítója. Nincs aláírva; csak a naplózáshoz |
poltura-attempt | A kísérlet sorszáma. Nincs aláírva; csak a naplózáshoz |
Hozz létre egy ellenőrzőt a @poltura/app-sdk/webhooks csomag createWebhookVerifier függvényével. Ez 1–8 nyilvános platformkulcsot fogad (Ed25519, PEM formátumban), kiválasztja a poltura-key-id headerben megadott kulcsot, és ha átadod a requiredStoreId és a requiredInstallationId paramétert is, elutasítja a más telepítésekre vonatkozó eseményeket. Az éles (production) kulcs még nincs közzétéve (lásd: Hitelesítés).
const verifierOptions: WebhookVerifierOptions = {
keys: [{ kid: env.POLTURA_WEBHOOK_KID, publicKeyPem: env.POLTURA_WEBHOOK_PUBLIC_KEY }],
};
if (env.POLTURA_INSTALLATION_ID !== undefined) {
verifierOptions.requiredStoreId = env.POLTURA_STORE_ID;
verifierOptions.requiredInstallationId = env.POLTURA_INSTALLATION_ID;
}
const verifier = createWebhookVerifier(verifierOptions);Ezután ellenőrizd az egyes kérések nyers bodyját, mielőtt felhasználnád:
const raw = await readBody(req);
const event = verifier.verify(raw, requestHeaders(req));
if (event.topic === PublicTopics.ORDER_CREATED) {
await saveLastOrder(client(), event.data.orderId, 0, event.eventId);
}
send(res, 200, event.topic);const raw = await readBody(req);
const event = verifier.verify(raw, requestHeaders(req));
send(res, 200, event.topic);A verify a típusos eseményt adja vissza. Egy újrapróbálkozás ugyanazt az eventId értéket tartalmazza új kézbesítési azonosítóval, ezért tárold el a már feldolgozott eventId értékeket, másodszorra pedig hagyd ki őket. A sikertelen ellenőrzés PolturaWebhookError hibát dob a következő hibakódok (code) egyikével: invalid, wrong_algorithm, unknown_kid, expired_timestamp, future_timestamp, noncanonical_signature, payload_too_large, altered_body vagy tenant_mismatch. Ezekre válaszolj 4xx-es hibakóddal.
Újrapróbálkozások
Az esemény nyugtázásához válaszolj 2xx kóddal 10 másodpercen belül. Ellenkező esetben a Poltura újrapróbálkozik, összesen legfeljebb 8 alkalommal, minden próbálkozásnál hosszabb ideig várakozva, 1 másodperctől egészen 5 percig. Az utolsó kísérlet után a Poltura feladja a kézbesítést. A válaszodból csak az első 64 KiB-ot olvassa be.
Az app.suspended és az app.uninstalled események a bolt által korábban jóváhagyott release célcímeire érkeznek, még akkor is, ha az appot már eltávolították. Ha az adott release nem tartalmazott hozzájuk célcímet, a Poltura nem küldi el őket.
Következő lépések
- Hitelesítés: ugyanez az aláírás a műveleteken.
- Jogosultságok és témakörök: az összes témakör, a platformból generálva.