Webhooks

Webhooks vám umožňují přijímat aktualizace v reálném čase od Meshy, když jsou vaše úlohy API dokončeny nebo změní stav. Po konfiguraci bude Meshy odesílat metodou POST event payloads 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 automatickou kontrolu stavů úloh API. Webhooks vyžadují méně úsilí a nákladů než průběžné dotazování API za účelem získávání aktualizací stavu úloh. Webhooks také umožňují aktualizace téměř v reálném čase a v konečném důsledku se škálují lépe než dotazování API. To vám také umožňuje lépe spravovat limity počtu požadavků, zejména pokud dotazování provádíte neustále.

Nastavení a konfigurace

Chcete-li povolit webhooks, přejděte po přihlášení do webové aplikace Meshy na stránku nastavení API. Najděte sekci "Webhooks" pod svými API key a klikněte na tlačítko "Vytvořit Webhook". Zadejte požadovanou https URL, ze které 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. Když je webhook povolen, všechny aktualizace stavu úloh API budou automaticky odesílány 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í Webhook

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

  • Váš server musí odpovědět 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í.
  • Více po sobě jdoucích selhání může:
    • Způsobit, že aktualizace progress budou zpožděné nebo dorazí mimo 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í Webhooks pro lokální testování

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

Získejte webhook proxy URL:

  1. V prohlížeči přejděte na https://smee.io/
  2. Klikněte na "Start a new channel"
  3. Zkopírujte úplnou 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 v terminálu následující příkaz.
npm install --global smee-client
  1. Chcete-li přijímat přeposlané webhooks ze smee.io, spusťte v terminálu následující příkaz. Nahraďte WEBHOOK_PROXY_URL svou dříve získanou webhook proxy URL.
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 to spuštěné, zatímco budete svůj webhook testovat. Když chcete přestat přeposílat webhooks, zadejte Ctrl+C.
    Všimněte si, že cesta je /webhook a port je 3000. Tyto hodnoty se vám mohou hodit, až budete později chtít nastavit vlastní kód pro přijímání doručení webhook.

Vytvoření webhook:

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

Ukázková odpověď

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