Webhooks

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

Proč vytvářet Webhooks

Používání webhooků má několik výhod, zejména pokud jde o automatickou kontrolu stavu API úloh. Webhooky vyžadují méně úsilí a nákladů než neustálé dotazování API kvůli získávání aktualizací stavu úloh. Webhooky také umožňují aktualizace téměř v reálném čase a v konečném důsledku lépe škálují než dotazování API. To vám také umožní lépe spravovat vaše rate limity, zejména pokud provádíte dotazování neustále.

Nastavení a konfigurace

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

Požadavky na doručování webhooků

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

  • Váš server musí odpovědět stavovým kódem HTTP 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í.
  • Vícenásobná po sobě jdoucí selhání mohou:
    • Způsobit, že aktualizace progressu budou zpožděné nebo doručené v nesprávném pořadí
    • Automaticky deaktivovat váš webhook po opakovaných pokusech (viz Zásady automatické deaktivace)

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

Přeposílání webhooků pro lokální testování

Pokud byste chtěli otestovat svůj kód webhooku lokálně, což je obvykle na http adrese, můžete použít webhook proxy URL k přeposílání webhooků na váš počítač nebo codespace. Níže jsou doporučené kroky s použitím smee.io, ale můžete použít jakoukoli službu, kterou chcete, ke generování webhook proxy URL.

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 adresu pod „Webhook Proxy URL“. Tuto URL adresu použijete v následujících krocích nastavení.

Přeposílání webhooků:

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

Měli byste vidět výstup, který vypadá takto, 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. Pokud chcete zastavit přeposílání webhooků, stiskněte Ctrl+C.
    Všimněte si, že cesta je /webhook a port je 3000. Tyto hodnoty se vám mohou hodit, až budete chtít později nastavit vlastní kód pro přijímání doručovaných webhooků.

Vytvoření webhooku:

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

Ukázková odpověď

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