Vytvořili jste zřizovací úlohu a dostali jste zpět 202: ID enginu a status: "in_progress". AI agent teď na pozadí prochází vaše zdroje a na tento engine aplikuje hlasy značky, položky glosáře a instrukce. Může to trvat chvilku, nebo taky déle, podle toho, kolik odkazů musí projít. Mohli byste nechat otevřený živý WebSocket a sledovat ho při práci – ale pravděpodobně nechcete držet spojení otevřené jen proto, abyste zjistili, že agent skončil, a co vytvořil.
Právě k tomu slouží webhook. Když při vytváření úlohy předáte callbackUrl, Lingo v okamžiku, kdy úloha skončí, odešle metodou POST finální výsledek na tuto URL – dostanete informaci, že je engine připravený, spolu s přehledem toho, co vzniklo. Úloha, která doběhne, dorazí jako provisioning.completed se souhrnem všech záznamů, které AI vytvořila. Úloha, která selže, dorazí jako provisioning.failed s důvodem. V obou případech se váš setup flow dozví výsledek bez dalšího dotazování.
Tato stránka popisuje oba payloady a jak s nimi pracovat. Doručení je podepsané a opakuje se – tento mechanismus je sdílený s lokalizací a je popsaný na stránce ověření podpisu webhooku, na kterou odkazujeme všude tam, kde ji budete potřebovat.
Na této stránce
- Jak doručování funguje
- Payload completed
- Payload failed
- Zpracování webhooku
- Kdy webhook není ten správný nástroj
Jak doručování funguje#
Zřizovací úloha skončí právě jednou. Ve chvíli, kdy dosáhne koncového stavu – všechny zdroje jsou prošlé a analyzované, nebo je běh ukončený – je její výsledek doručen na vaši callbackUrl jako jediný POST. Lokalizační skupina se rozpadá na jednu úlohu pro každý cílový jazyk, z nichž každá posílá vlastní callback; zřizovací úloha je jen jedna, takže má i jedno doručení.
Cíl nastavíte pomocí callbackUrl, když vytváříte úlohu. Přes rozhraní se přenášejí dva typy payloadu, rozlišené polem type: provisioning.completed a provisioning.failed. Oba uvádějí jobId a engineId, ke kterým patří, takže jeden handler může směrovat podle type a aktualizovat správný záznam.
Pouze HTTPS
callbackUrl musí používat HTTPS. HTTP adresa URL se při vytváření úlohy odmítne – webhook je podepsaný a posílat podepsaný payload přes nešifrovaný přenos by popíralo smysl celého řešení.
Neznámé typy událostí zpracovávejte korektně
Dnes se přes rozhraní přenáší provisioning.completed a provisioning.failed. Berte tuto množinu jako otevřenou – větvěte podle typů, které znáte, a ostatní ignorujte, aby budoucí typ události nerozbil už nasazený handler.
Payload completed#
Když úloha skončí, payload obsahuje summary – stejný přehled, jaký byste získali načtením úlohy, jen vám přijde rovnou místo průběžného dotazování. Uvádí každý hlas značky, položku glosáře a instrukci, které AI na vašem enginu vytvořila, a vypisuje i všechna dílčí selhání, na která po cestě narazila.
{
"type": "provisioning.completed",
"jobId": "pjb_A1b2C3d4E5f6G7h8",
"engineId": "eng_X1y2Z3a4B5c6D7e8",
"summary": {
"brandVoices": { "count": 3, "ids": ["bv_A1b2C3d4", "bv_B2c3D4e5", "bv_C3d4E5f6"] },
"glossaryItems": { "count": 12, "ids": ["gi_A1b2C3d4", "..."] },
"instructions": { "count": 5, "ids": ["ins_A1b2C3d4", "..."] },
"errors": []
}
}| Pole | Popis |
|---|---|
type | provisioning.completed |
jobId | Zřizovací úloha, která skončila (prefix pjb_) |
engineId | Engine, který nakonfigurovala (prefix eng_) |
summary | Co AI na enginu vytvořila – počty a ID podle jednotlivých komponent plus dílčí selhání v errors |
summary je stejný objekt, který nese i samotná úloha, a jeho význam pole po poli – co která komponenta znamená, jak se položky mapují na jazyky a co se objeví v errors – je zdokumentovaný na jednom místě na stránce Co AI extrahuje. Tady stačí vědět, že payload completed vám předá ID všeho, co agent vytvořil, takže je váš handler může uložit nebo zobrazit v dashboardu bez nutnosti znovu načítat úlohu.
Neprázdné pole errors stále přichází jako completed.
Dílčí selhání neznamenají selhání celé úlohy. Pokud nešel projít jeden zdroj nebo se nepodařilo vytvořit jeden záznam, objeví se v summary.errors a zbytek se na engine přesto aplikuje – a payload je stále provisioning.completed, ne provisioning.failed. Událost completed znamená, že úloha doběhla do konce; v errors uvidíte, co je potřeba opravit. Payload provisioning.failed se odesílá tehdy, když běh nevytvořil vůbec žádný použitelný engine.
Payload failed#
Zřizovací úloha selže, když běh nevytvoří nic, s čím by se dalo pracovat – například když se nepodaří projít žádný zdroj, takže agent nemá žádný obsah k analýze. I v takovém případě se to dozvíte. Typ payloadu je provisioning.failed a místo souhrnu obsahuje řetězec error:
{
"type": "provisioning.failed",
"jobId": "pjb_A1b2C3d4E5f6G7h8",
"engineId": "eng_X1y2Z3a4B5c6D7e8",
"error": "All sources failed to crawl. No content available for analysis."
}| Pole | Popis |
|---|---|
type | provisioning.failed |
jobId | Zřizovací úloha, která selhala |
engineId | Engine, který byl vytvořen, ale zůstal nenakonfigurovaný |
error | Lidsky čitelný důvod, proč úlohu nešlo dokončit |
Tady přichází otázka, kterou si skeptický čtenář oprávněně položí: když úloha selhala, přišel jsem i o engine? Nepřišli jste. engineId v tomto payloadu je stejný engine, který jste dostali v 202 – stále existuje, vznikl ve chvíli, kdy jste volání provedli, jen bez konfigurace, kterou by neúspěšný běh přidal. Selhání vás stojí jen extrakci, nikdy ne engine. Upravte to, co jste odeslali, a zkuste to znovu, nebo engine nakonfigurujte ručně v dashboardu. Když úloha selže při procházení zdrojů, bývá problém právě v nich – stránka Typy zdrojů vysvětluje, co dělá zdroj vhodným kandidátem.
Zpracování webhooku#
První myšlenka skeptického čtenáře je tady správná: můj handler dělá skutečnou práci – zapisuje do databáze, posílá notifikace, obnovuje dashboard – nebude tedy držet spojení otevřené tak dlouho, že webhook vyprší?
Bude, takže nenechávejte Lingo čekat. Nejdřív vraťte 200, potom zpracovávejte. Potvrďte přijetí a skutečnou práci udělejte až po odeslání odpovědi. Celý kontrakt doručování – proč potvrzujete nejdřív a jaký harmonogram opakování následuje, když to neuděláte – je na stránce podpis a doručování; handler níže ukazuje, jak to vypadá u zřizovacího payloadu.
app.post("/webhooks/provisioning", verifyWebhook, async (req, res) => {
// Acknowledge first - the job ends once, so this fires once.
res.status(200).send("ok");
const { type, jobId, engineId } = req.body;
if (type === "provisioning.completed") {
const { summary } = req.body;
await db.engines.update({
where: { engineId },
data: {
status: "ready",
brandVoiceCount: summary.brandVoices.count,
glossaryCount: summary.glossaryItems.count,
instructionCount: summary.instructions.count,
},
});
}
if (type === "provisioning.failed") {
console.error(`Provisioning failed: ${jobId} (${engineId})`, req.body.error);
await db.engines.update({
where: { engineId },
data: { status: "needs_configuration" },
});
}
});Middleware verifyWebhook je jediná část, kterou tato stránka nedefinuje. Každé doručení je podepsané podle specifikace Standard Webhooks – tři hlavičky, HMAC nad surovým tělem a tajný klíč whsec_, který se vygeneruje při prvním odeslání úlohy s callbackem. Callbacky pro zřizování i lokalizaci používají toto schéma beze změny, takže je jednou popsané na stránce ověření podpisu webhooku. Zapojte middleware dřív, než začnete payloadu důvěřovat – neověřené tělo je neautentizované.
Nejdřív ověřte, teprve potom věřte tělu požadavku
Váš endpoint je veřejná URL; kdokoli na ni může poslat POST. Než na základě payloadu něco provedete, ověřte podpis vůči surovému tělu požadavku – ještě předtím, než označíte engine jako připravený nebo uložíte ID, která údajně vytvořil. Jak na to – hlavičky, HMAC, tajný klíč whsec_ – popisuje stránka ověření podpisu.
Kdy webhook není ten správný nástroj#
Webhook je pohodlný push mechanismus, ne systém záznamu. Ve dvou případech je lepší sáhnout po něčem jiném – a obojí najdete o jeden odkaz dál.
Pokud byl váš endpoint v době doručení výsledku nedostupný, platforma opakuje pokusy podle stejného harmonogramu, který používá každý webhook od Lingo – a výsledek nezůstane uvězněný v callbacku. Záznamy, které AI vytvořila, jsou skutečnou konfigurací enginu; completed summary je zpráva o práci, která už proběhla na skutečném enginu, ne její jediná kopie. Výpadek vás tedy stojí notifikaci, nikdy ne engine. Samotný harmonogram opakování je na stránce podpis a doručování.
A pokud chcete živý průběh během konfigurace enginu – stav v UI ve smyslu procházení a následné konfigurace místo jediného callbacku na váš server po skončení – pak potřebujete WebSocket zřizovací úlohy, ne webhook. Ten streamuje snapshot při připojení a události průběhu podle toho, jak běh pokračuje, a připojit se můžete kdykoli, i po dokončení úlohy.
