lowpoly bude vyřazen 30. 10. 2026. Před těmito daty přejděte na jiný model, abyste předešli chybám požadavků.

Webhooks

Webhooks vám umožňují přijímat aktualizace v reálném čase od Meshy, jakmile se vaše API úlohy dokončí nebo změní stav. Po nakonfigurování bude Meshy odesílat event payloady ve formátu json na vámi zadané URL.

Proč vytvářet Webhooks

Používání webhooks má několik výhod, zejména pokud jde o automatické zjišťování stavu API úloh. Webhooks vyžadují méně úsilí a nákladů než neustálé dotazování API kvůli získání aktualizací stavu úlohy. Webhooks zároveň umožňují téměř okamžité aktualizace v reálném čase a v konečném důsledku se lépe škálují než dotazování API. Díky tomu také lépe spravujete své rate limity, zejména pokud se dotazujete neustále.

Nastavení a konfigurace

Pro povolení webhooks otevřete stránku Webhooks na Developer Platform a klikněte na tlačítko „Create Webhook“. Zadejte požadovanou https URL, na kterou chcete přijímat webhooks, a povolte webhook, aby automaticky přijímal aktualizace úloh od Meshy. Na jeden účet Meshy můžete mít maximálně 5 aktivních webhooks. Jakmile je webhook povolen, všechny aktualizace stavu API úloh se automaticky odesílají na payload URL. Z bezpečnostních důvodů v tuto chvíli povolujeme odesílání webhooks pouze na https URL. Pokud chcete nakonfigurovat lokální testování, podívejte se na následující sekci.

Požadavky na doručování Webhooks

Aby váš webhook fungoval normálně a nadále přijímal eventy:

  • Váš server musí odpovědět s HTTP stavovým kódem nižším než 400 (např. 200 OK, 202 Accepted).
  • Jakákoli odpověď se stavovým kódem >= 400 bude považována za neúspěšné doručení.
  • Opakované po sobě jdoucí selhání mohou:
    • Způsobit zpoždění aktualizací progress nebo jejich doručení v nesprávném pořadí
    • Po opakovaných pokusech automaticky deaktivovat váš webhook (viz zásady automatické deaktivace)

Tip: Vždy po ověření a uložení webhook payloadu vraťte úspěšnou odpověď, i když další zpracování probíhá asynchronně.

Pokud finální event úlohy nedorazí ani po přibližně dvojnásobku jejího typického trvání, získejte úlohu pomocí jejího GET koncového bodu. Typické časy a doporučenou dobu čekání najdete v Životním cyklu úlohy.

Přeposílání Webhooks pro lokální testování

Pokud chcete svůj kód pro webhook otestovat lokálně, což je typicky na http adrese, můžete pro přeposílání webhooks do svého počítače nebo codespace použít webhook proxy URL. Níže jsou doporučené kroky s využitím smee.io, ale pro generování webhook proxy URL můžete použít libovolnou službu, kterou chcete.

Získání webhook proxy URL:

  1. Ve svém prohlížeči přejděte na https://smee.io/
  2. Klikněte na „Start a new channel“
  3. Zkopírujte celou URL pod „Webhook Proxy URL“. Tuto URL použijete v následujících krocích nastavení.

Přeposílání webhooks:

  1. Pokud ještě nemáte nainstalovaný smee-client, spusťte ve svém terminálu následující příkaz.
npm install --global smee-client
  1. Pro přijímání přeposílaných webhooks ze smee.io spusťte ve svém terminálu následující příkaz. Nahraďte WEBHOOK_PROXY_URL svou webhook proxy URL z předchozího kroku.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Měli byste vidět výstup podobný tomuto, kde WEBHOOK_PROXY_URL je vaše webhook proxy URL:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Nechte toto běžet, dokud testujete svůj webhook. Až budete chtít přeposílání webhooks zastavit, zadejte Ctrl+C.
    Všimněte si, že cesta je /webhook a port je 3000. Tyto hodnoty se vám mohou hodit, pokud si později budete chtít nastavit vlastní kód pro přijímání doručování webhooks.

Vytvoření webhooku:

Nyní můžete použít webhook proxy URL k vytvoření nového webhooku na stránce Webhooks.

Ukázková odpověď

Když se změní stav úlohy, Meshy odešle webhook payload metodou POST na vámi nakonfigurovanou URL. Payload obsahuje objekt úlohy ve formátu JSON. Úplný popis všech vlastností objektu úlohy a ukázkové payloady najdete zde: