Kimenő webhookok

Ellenőrizveellenőrizve 2026-10-06

Röviden

A webhook a REST és az MCP ellentéte: nem Ön kérdez, hanem a MitoOps jelentkezik. Amikor a fiókjában olyan esemény történik, amelyre feliratkozott, rövid, aláírt borítékot küldünk POST kéréssel az Ön címére. A boríték azonosítókat és állapotokat hordoz, nem a rendelés tartalmát: a részleteket az Ön rendszere a REST interfészen keresztül tölti be a saját kulcsával.

A feliratkozásokat az alkalmazásban kezeli: Beállítások → API & MCP → Kimenő webhookok. A Start tarifától érhetők el; a Kimenő webhookok jogosultság szükséges hozzájuk (olvasás vagy kezelés).

Feliratkozás (végpont)

A végpontnak van neve, címe, eseménylistája és webáruház-hatóköre. Létrehozáskor titkos kulcsot kap: egyszer jelenik meg, aztán soha többé; bármikor lecserélheti (rotálás), a régi pedig azonnal érvényét veszti.

A címnek nyilvánosnak kell lennie, és https:// protokollt kell használnia a szabványos porton. A belső hálózatra mutató címeket (helyi gép, privát tartományok, felhő-metaadatok, VPN-tartományok) a rendszer mentéskor és minden kézbesítéskor is elutasítja: a nevet újra feloldja, és a kapcsolatot az ellenőrzött címekhez köti.
Az átirányításokat nem követjük. A 3xx válasz sikertelenségnek számít.
Webáruházak: mind (a később hozzáadottakat is) vagy a kiválasztottak. A hatókörön kívüli webáruház eseménye nem kerül elküldésre.
A gombbal indított teszt kézbesítés ping eseményt küld ugyanazon az úton, mint az éles kézbesítés, az aláírással és a naplóbejegyzéssel együtt.
A végpont kikapcsolható (a várakozó kézbesítések kimaradnak) és törölhető (a napló megmarad).

Események

Esemény	Mikor	`resource.type`	Mezők a `data` objektumban
`order.created`	új rendelés a webáruházból	`order`	`order_code`
`order.paid`	a rendelés fizetettként megjelölve	`order`	`order_code`
`order.status_changed`	a rendelés állapotának változása	`order`	`order_code`, `status_id`, `previous_status_id`
`shipment.created`	küldemény létrehozva a szállítónál	`shipment`	`shipment_id`, `order_code`, `carrier_code`, `tracking_number`
`shipment.status_changed`	a küldemény állapotának változása (szállító vagy munkatárs által)	`shipment`	`shipment_id`, `order_code`, `carrier_code`, `status`, `previous_status`, `tracking_number`
`shipment.delivered`	küldemény kézbesítve; a `shipment.status_changed` mellett	`shipment`	mint fent, a `status` értéke `DELIVERED`
`inventory.stock_changed`	egy tétel készletmozgása	`inventory_item`	`item_id`, `sku`, `kind`
`invoice.created`	kiállított számla	`invoice`	`invoice_code`, `order_code`
`claim.created`	létrehozott reklamáció (az ügyfél vagy egy munkatárs által)	`claim`	`claim_code`, `order_code`
`claim.status_changed`	a reklamáció állapotának változása	`claim`	`claim_code`, `order_code`, `status_id`
`claim.closed`	reklamáció lezárva	`claim`	`claim_code`, `order_code`
`search_console.connection.changed`	a Search Console kapcsolat állapota megváltozott (csatlakozás, webhelyváltás, hozzáférés elvesztése, leválasztás)	`search_console_property`	`market`, `status`, `previous_status`, `property`, `previous_property`, `changed_at`
`search_console.sync.completed`	az archívum szinkronizálása napokat adott hozzá vagy módosított	`search_console_property`	`market`, `property`, `search_types`, `data_state`, `final_data_through`, `fresh_data_through`, `days_upserted`, `revised_dates`, `sync_version`, `synced_at`
`search_console.sync.failed`	az archívum szinkronizálása sikertelen	`search_console_property`	`market`, `property`, `error`, `error_code`, `last_successful_sync_at`, `retry_at`
`product_content.changed`	A MitoOps megváltozott termékleírást, rövid leírást vagy SEO-szöveget írt a webshopba	`product`	`store_id`, `market`, `entity`, `entity_id`, `canonical_url`, `source`, `source_run_id`, `changed_fields`, `before_hash`, `after_hash`, `changed_at`
`category_content.changed`	A MitoOps megváltozott felső vagy alsó kategórialeírást vagy SEO-szöveget írt a webshopba	`category`	mint a `product_content.changed` esetén
`ping`	teszt kézbesítés a gombbal	`webhook_endpoint`	`message`, `endpoint`

Az események ugyanabból az üzleti rétegből származnak, mint az automatizálások: ami automatizálást indít, arra webhookkal is fel lehet iratkozni. A visszaküldemények (visszáruk) nem shipment.* eseményként kerülnek elküldésre, mert a reklamációhoz tartoznak.

Termék- és kategóriaszövegek változása

A product_content.changed és a category_content.changed írásonként és webshoponként egyszer jön létre, amikor a MitoOps ténylegesen megváltozott szöveget ír a webshopba — a termékkártyáról, tömeges szerkesztésből, importból, a kategóriák képernyőjéről, jóváhagyott javaslatból vagy önálló írásból. Ár, készlet vagy kód változása, illetve ugyanannak a szövegnek az ismételt mentése nem vált ki eseményt. A közvetlenül a webshop adminisztrációjában végzett módosításokat ez az esemény nem jelzi.

Az entity értéke product vagy category; az entity_id (és a resource.id) a termékkód, illetve a kategória azonosítója a webshopban — ugyanazok, amelyekkel a szövegeket a products_content_get és a categories_content_get segítségével olvassa. A store_id a webshop kódja, azonos a store értékével.
source: ui (személy az alkalmazásban), assistant (az alkalmazás asszisztense), mcp (MCP-n keresztül készült, személy által jóváhagyott javaslat), autonomous (önálló módban beírt javaslat). A rest érték fenntartott — a REST ma csak olvasható.
source_run_id: a javaslat azonosítója jóváhagyott és önálló írásnál; a termék egyéb írásainál az írási köteg azonosítója (Termékváltozások); javaslaton kívül mentett kategóriánál null.
A changed_fields felsorolja a megváltozott mezőket: terméknél description, shortDescription, metaTitle, metaDescription, kategóriánál description, descriptionBottom, metaTitle, metaDescription. A before_hash és az after_hash mindegyikhez a szöveg UTF-8 SHA-256 lenyomatát tartalmazza (hiányzó érték = az üres karakterlánc lenyomata) — ugyanazt az értéket, amelyet olvasáskor a hash mező ad. Magát a szöveget a boríték nem tartalmazza.
Javaslat jóváhagyása után az after_hash annak a lenyomata, amit a webshop az írás után ténylegesen eltárolt (a WordPress például eltávolítja a <style> blokkot), nem pedig a javasolt szövegé.
A canonical_url a termék vagy kategória nyilvános címe, ha a MitoOps ismeri; különben null.

Hogy a kulcsa az adott webshopban mit olvashat és javasolhat, és hogy a javaslat magától beíródik-e, előre megtudja a tartalomszabályzatból: GET /api/v1/product-content/policy?market=… vagy a products_content_policy MCP-eszköz (product-content:read hatókör).

Boríték

Minden kézbesítés JSON, a boríték verziójával. Új mező a verzió megváltoztatása nélkül is megjelenhet; egy mező jelentésének megváltozása új verziót jelent.

{
  "event_id": "9b2f0c1e-6d3a-4c7e-9a2b-0f1e2d3c4b5a",
  "event_type": "shipment.delivered",
  "version": 1,
  "occurred_at": "2026-09-03T08:41:12.318Z",
  "tenant": "00001",
  "store": "sk",
  "resource": { "type": "shipment", "id": "5521" },
  "data": {
    "shipment_id": "5521",
    "order_code": "2026001234",
    "carrier_code": "gls",
    "status": "DELIVERED",
    "previous_status": "IN_TRANSIT",
    "tracking_number": "GLS123456789"
  }
}

Az event_id eseményenként egyedi. Ha ugyanarra az eseményre két végpontja is fel van iratkozva, ugyanazt az azonosítót kapják. Az újrapróbálkozás ugyanazt az azonosítót és ugyanazt a törzset hordozza.
A store a webáruház kódja (market), ugyanaz, amelyet a REST használ.
A tenant az Ön MitoOps-fiókjának azonosítója.

Fejlécek és aláírás

Content-Type:          application/json
User-Agent:            MitoOps-Webhooks/1
X-MitoOps-Event:       shipment.delivered
X-MitoOps-Event-Id:    9b2f0c1e-6d3a-4c7e-9a2b-0f1e2d3c4b5a
X-MitoOps-Timestamp:   1756888872
X-MitoOps-Signature:   v1=3f1a…c9e0
X-MitoOps-Delivery:    184

Az aláírás HMAC-SHA256, amelynek kulcsa a végpont titkos kulcsa, és a következő karakterláncra készül:

<X-MitoOps-Timestamp> + "." + <a kérés pontos törzse>

Az eredmény hexadecimális, és a fejlécben a v1= verzióelőtaggal szerepel. Az időbélyeg Unix-idő másodpercben.

Ellenőrzés az Ön oldalán

Az ellenőrzést a kérés nyers törzsén végezze (a bájtokon úgy, ahogy megérkeztek), ne az újraszerializált JSON-on: egy szóköz vagy a kulcsok sorrendjének bármilyen változása érvényteleníti az aláírást. Konstans idejű összehasonlítást használjon, és utasítsa el az 5 percnél régebbi üzeneteket.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyMitoOpsWebhook({ secret, headers, rawBody, now = Math.floor(Date.now() / 1000) }) {
  const ts = Number(headers['x-mitoops-timestamp']);
  if (!Number.isFinite(ts) || Math.abs(now - ts) > 300) return false;   // régi vagy hiányzó időbélyeg

  const received = String(headers['x-mitoops-signature'] || '')
    .split(',').map((s) => s.trim()).find((s) => s.startsWith('v1='));
  if (!received) return false;

  const expected = createHmac('sha256', secret)
    .update(String(ts) + '.').update(rawBody).digest('hex');
  const a = Buffer.from(received.slice(3), 'hex');
  const b = Buffer.from(expected, 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

import hmac, hashlib, time

def verify_mitoops_webhook(secret: str, headers: dict, raw_body: bytes) -> bool:
    try:
        ts = int(headers["X-MitoOps-Timestamp"])
    except (KeyError, ValueError):
        return False
    if abs(int(time.time()) - ts) > 300:
        return False
    sig = next((s.strip() for s in headers.get("X-MitoOps-Signature", "").split(",") if s.strip().startswith("v1=")), None)
    if not sig:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig[3:], expected)

Visszajátszás elleni védelem

Az aláírás lefedi az időbélyeget, így egy elfogott üzenetet később nem lehet új időponttal elküldeni. Az időellenőrzés mellett tárolja a legutóbbi kézbesítések event_id értékét, és hagyja figyelmen kívül az ismétlődéseket: az ismételt kézbesítés a rendszer tulajdonsága, nem hiba.

Válasz, újrapróbálkozás és napló

Válaszoljon 2xx kóddal 10 másodpercen belül. A válasz törzsét nem olvassuk. A hosszabb ideig tartó feldolgozást tegye háttérbe, és válaszoljon azonnal.
Minden más válasz (4xx, 5xx), időtúllépés vagy kapcsolódási hiba sikertelenségnek számít, és újrapróbálkozás következik 1, 5, 15, 60 és 240 perces késleltetéssel; összesen hat kísérlet. Ezután a kézbesítés állapota FAILED, és a naplóból indítható kézi újrapróbálkozásra vár.
A 3xx válasz és az a cím, amely már nem nyilvános hálózatra oldódik fel, újrapróbálkozás nélküli sikertelenségnek számít: ezek maguktól nem oldódnak meg.
Az alkalmazás kézbesítési naplója minden kísérletnél megmutatja az állapotot, a HTTP-kódot, az időt, a kísérletek számát és az eseményt. Az üzenet törzse a naplóban nem jelenik meg.

Állapot	Jelentés
`PENDING`	kísérletre vagy a következő újrapróbálkozásra vár
`SENT`	a fogadó `2xx` kóddal válaszolt
`FAILED`	a kísérletek elfogytak, vagy tartós hiba történt; kézzel újrapróbálható
`SKIPPED`	a végpontot időközben kikapcsolták vagy törölték

Biztonság

A titkos kulcs titkosítva tárolódik, és soha nem kerül a naplókba vagy a kézbesítési naplóba. Egyszer jelenik meg; a rotálás akkor is működik, ha a tarifa már nem tartalmaz webhookokat, mert ez biztonsági művelet.
Személyes adatok nélkül. A boríték azonosítókat és állapotokat hordoz. Az ügyfél neve, címe és e-mail-címe nem kerül elküldésre; akinek szüksége van rájuk, REST-en keresztül olvassa őket saját hatókörrel és auditnaplóval.
Csak HTTPS, csak nyilvános címek, átirányítások nélkül. A mentéskor és minden kézbesítéskor végzett ellenőrzés véd a belső hálózatba irányítás és a DNS megváltoztatása ellen.
A feliratkozást ember hozza létre, nem kulcs. Sem a REST hozzáférési kulcs, sem az OAuth hozzájárulás nem hozhat létre feliratkozást: az igény szerinti olvasás és az események állandó, kifelé irányuló folyama két különböző jogosultság.
Elkülönítés. A feliratkozások és a napló az Ön fiókjának terében vannak; a webáruház-hatókört a rendszer minden eseménynél kiértékeli.

Tarifa

Tarifa	Kimenő webhookok	Végpontok
Próbaverzió	nem	0
Kezdő	nem	0
Start	igen	5
Növekedés	igen	20
Pro	igen	50
Egyedi	megállapodás szerint	megállapodás szerint

A nem törölt végpontok számítanak bele, a bekapcsoltak és a kikapcsoltak is. A tarifa csökkentése a meglévő végpontokat nem törli; új végpont nem adható hozzá, amíg a számuk a limit alá nem csökken, és webhookok nélküli tarifánál az események küldése leáll, amíg a tarifa vissza nem áll.

Webhook automatizálásból

A végpontot az Automatizálás modulban a Webhook küldése lépésként is használhatja: az üzenet csak a szabály feltételeinek teljesülése után megy el, nem minden eseménynél. A lépés csak kiválasztja a végpontot: a cím, a titkos kulcs és a webáruház-hatókör a nyilvántartásban marad.

Az üzenet típusa automation.action (erre közvetlenül nem lehet feliratkozni), és ugyanaz a boríték, aláírás, újrapróbálkozás és napló vonatkozik rá, mint a többi eseményre. A data objektumban az automation.workflow_id, automation.run_id, automation.node_id, automation.source_event (az esemény, amely a szabályt elindította) értéket, valamint a rendelés, a küldemény vagy a reklamációs ügy azonosítóit hordozza; a resource a futás entitása. A részleteket a REST API-n keresztül töltheti be.

Automatikus felfüggesztés

Ha a fogadó 30 egymást követő kísérletre nem válaszol, vagy a végpontnak 5000-nél több várakozó kézbesítése van, a MitoOps felfüggeszti a végpontot, és értesítést küld Önnek. A várakozó kézbesítések megmaradnak; a fogadó javítása után kapcsolja be a végpontot, és a kézbesítések pótlólag lefutnak. A kézbesítési naplót 30 napig őrizzük.