Webhooks

Webhooks vám umožňují přijímat aktualizace v reálném čase od Meshy, když jsou vaše API úkoly dokončeny nebo změní stav. Jakmile jsou nakonfigurovány, Meshy bude odesílat POST události payload ve formátu json na URL, které určíte.

Proč vytvořit Webhooks

Použití webhooks má několik výhod, zejména pokud jde o automatické sledování stavů API úkolů. Webhooks vyžadují méně úsilí a nákladů než neustálé dotazování API pro získání aktualizací stavů úkolů. Webhooks také umožňují téměř okamžité aktualizace a nakonec lépe škálují než dotazování API. To vám také umožňuje lépe spravovat vaše limity rychlosti, zejména pokud neustále dotazujete.

Nastavení a konfigurace

Pro povolení webhooks přejděte na stránku nastavení API po přihlášení do webové aplikace Meshy. Najděte sekci "Webhooks" pod vašimi API klíči a klikněte na tlačítko "Vytvořit Webhook". Zadejte požadovanou https URL pro příjem webhooks a povolte webhook pro automatické přijímání aktualizací úkolů od Meshy. Můžete mít maximálně 5 aktivních webhooks na účet Meshy. Když je webhook povolen, všechny aktualizace stavů API úkolů budou automaticky odesílány na payload URL. Z bezpečnostních důvodů v současné době povolujeme odesílání webhooks pouze na https URL. Pokud byste chtěli nakonfigurovat lokální testování, viz následující sekce.

Požadavky na doručení Webhook

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

  • Váš server musí odpovědět s HTTP stavovým kódem pod 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íce po sobě jdoucích neúspěchů může:
    • Způsobit zpoždění aktualizací progress nebo jejich příchod v nesprávném pořadí
    • Automaticky deaktivovat váš webhook po opakovaných pokusech (viz Politika automatické deaktivace)

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

Přesměrování Webhooks pro lokální testování

Pokud byste chtěli testovat váš webhook kód lokálně, což je typicky na http adrese, můžete použít webhook proxy URL pro přesměrování webhooks na váš počítač nebo codespace. Níže jsou doporučené kroky pomocí smee.io, ale můžete použít jakoukoli službu, kterou chcete, pro generování webhook proxy URL.

Získání webhook proxy URL:

  1. Ve vašem 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řesměrování webhooks:

  1. Pokud ještě nemáte nainstalovaný smee-client, spusťte následující příkaz ve vašem terminálu.
npm install --global smee-client
  1. Pro příjem přesměrovaných webhooks ze smee.io spusťte následující příkaz ve vašem terminálu. Nahraďte WEBHOOK_PROXY_URL vaší webhook proxy URL z dřívějška.
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, zatímco testujete váš webhook. Když chcete zastavit přesměrování webhooks, zadejte Ctrl+C.
    Všimněte si, že cesta je /webhook a port je 3000. Tyto hodnoty se mohou hodit, když budete chtít nastavit váš vlastní kód pro příjem doručení webhooků později.

Vytvoření webhooku:

Nyní můžete použít webhook proxy URL pro vytvoření nového webhooku na stránce nastavení Meshy API.

Ukázková odpověď

Když se změní stav úkolu, Meshy odešle POST webhook payload na vaši nakonfigurovanou URL. Payload obsahuje objekt úkolu ve formátu JSON. Pro úplný popis všech vlastností objektu úkolu a příkladů payloadů, viz: