Webhooks

Nechte Meshy poslat na váš server požadavek POST, když API úloha pokročí nebo skončí, abyste nemuseli stav zjišťovat dotazováním.

Proč používat webhooks

Webhooks vyžadují méně práce a stojí méně než dotazování API na stav každé úlohy. Meshy odesílá každou aktualizaci ihned, jak nastane, takže ji dostanete dříve, a webhooks se lépe škálují než dotazování. Odesíláte také méně požadavků, čímž zůstáváte dál od svých rate limitů.

Nastavení webhooku

Chcete-li přidat webhook, postupujte podle těchto kroků:

Otevřete stránku Webhooks v Developer Platform a klikněte na Create Webhook.
Do pole Payload URL zadejte URL, která bude přijímat doručení. Meshy doručuje pouze přes https://.
Uschovejte si kopii Webhook Secret, kterou dialog vyplní. Každé doručení ho obsahuje, takže váš server může ověřit, že požadavek pochází od Meshy. U webhooku, který už máte, zobrazíte secret kliknutím na ikonu oka ve sloupci Secret.
Zaškrtněte Active a klikněte na Confirm.

Každý účet může mít 5 aktivních webhooks a 10 celkem. Každý aktivní webhook dostává aktualizace stavu všech vašich API úloh.

Chcete-li webhook otestovat se serverem na svém počítači, viz Testování na vašem počítači.

Zpracování doručení

Chcete-li doručení přijmout, odpovězte stavem nižším než 400, například 200 nebo 202. Meshy čeká na odpověď přibližně 25 sekund, takže doručení nejprve uložte a odpovězte. Pomalejší práci, jako je stahování modelu, proveďte až poté.

Stav 400 nebo vyšší, případně žádná odpověď, se počítá jako neúspěšné doručení. Meshy ho zopakuje s postupně delšími prodlevami mezi pokusy, až 4krát u aktualizace IN_PROGRESS a až 9krát u finálního stavu. Pokud selže 20 aktualizací po sobě při každém pokusu, Meshy může webhook deaktivovat. Chcete-li ho znovu zapnout, upravte ho na stránce Webhooks a zaškrtněte Active.

Kód pište s ohledem na tyto případy:

Doručení mohou přijít v jiném pořadí. Doručení IN_PROGRESS může přijít až po finálním, takže ho nenechte finální stav přepsat.
Stejná aktualizace může přijít víckrát. Každou dvojici id a status zpracujte jen jednou.
Požadavek na vaši URL může poslat kdokoli, kdo ji zná. Porovnejte X-MESHY-API-WEBHOOK-SECRET-KEY se svou kopií secretu a požadavek, který neodpovídá, odmítněte.

Pokud finální doručení úlohy nedorazí ani po zhruba dvojnásobku jejího typického trvání, získejte úlohu z jejího koncového bodu GET. Typické doby trvání a to, jak dlouho čekat, najdete v části Životní cyklus úlohy.

Testování na vašem počítači

Meshy doručuje pouze na veřejnou URL https://, takže nedokáže přímo oslovit server na vašem počítači. Chcete-li otestovat kód na svém počítači, přesměrujte na něj veřejnou URL pomocí webhook proxy. Tyto kroky používají smee.io, přičemž stejným způsobem funguje jakákoli služba typu webhook proxy.

Otevřete smee.io a klikněte na Start a new channel. Zkopírujte URL pod Webhook Proxy URL.
Pokud ještě nemáte klienta smee, nainstalujte ho:
```
npm install --global smee-client
```
Přesměrujte kanál na svůj server. Nahraďte WEBHOOK_PROXY_URL svou webhook proxy URL:
```
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
```
Výstup bude vypadat 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
```
Nechte ho běžet po dobu testování. Přesměrování zastavíte stisknutím Ctrl+C. Váš server přijímá doručení na portu 3000 na cestě /webhook, takže na ní nastavte svůj kód, aby naslouchal.
Na stránce Webhooks vytvořte webhook s webhook proxy URL jako jeho Payload URL.

Payload doručení

Meshy odešle doručení, zatímco je úloha ve stavu IN_PROGRESS, a další, jakmile úloha dosáhne finálního stavu. Úloha může dosáhnout finálního stavu i bez doručení IN_PROGRESS.

Každé doručení je požadavek POST na vaši Payload URL s těmito hlavičkami:

Hlavička	Hodnota
`X-MESHY-API-WEBHOOK-SECRET-KEY`	Secret webhooku
`X-MESHY-API-WEBHOOK-USER-ID`	ID uživatele Meshy, kterému webhook patří
`Meshy-Webhook-Version`	`v1`, formát těla
`Content-Type`	`application/json`
`User-Agent`	`MeshyAPIWebhook/1.0.0`

Tělo JSON je objekt úlohy. Je to tentýž objekt, který vrací koncový bod GET dané úlohy, kromě progress. Doručení posílá progress jako jednu z těchto hodnot:

50, pokud je úloha ve stavu IN_PROGRESS
100, když úloha uspěje
0, když úloha selže nebo je zrušena

Pole jednotlivých objektů úloh s příklady najdete v následujících částech: