Webhooks

Ang Webhooks ay nagbibigay-daan sa iyo na makatanggap ng real-time updates mula sa Meshy kapag ang iyong API tasks ay natapos na o nagbago ang status. Kapag na-configure na, ang Meshy ay mag-POST ng event payloads sa json format papunta sa mga URL na iyong itinakda.

Bakit Gumawa ng Webhooks

Ang paggamit ng webhooks ay may ilang mga bentahe, lalo na pagdating sa awtomatikong pag-check ng API task statuses. Ang webhooks ay nangangailangan ng mas kaunting effort at gastos kaysa sa patuloy na pag-poll sa API para makuha ang task status updates. Ang webhooks ay nagbibigay din ng malapit sa real-time updates at sa huli ay mas maayos mag-scale kaysa sa API polling. Nakakatulong din ito para mas mahusay mong mapamahalaan ang iyong rate limits, lalo na kung ikaw ay patuloy na nagpo-poll.

Setup at Configuration

Para i-enable ang webhooks, buksan ang Webhooks page sa Developer Platform at i-click ang "Create Webhook" na button. Ibigay ang iyong nais na https URL kung saan mo gustong tumanggap ng webhooks at i-enable ang webhook para awtomatikong makatanggap ng task updates mula sa Meshy. Maaari kang magkaroon ng maximum na 5 aktibong webhooks bawat Meshy account. Kapag na-enable ang isang webhook, lahat ng API task status updates ay awtomatikong ipapadala sa payload URL. Para sa mga layuning pangseguridad, sa ngayon ay pinapayagan lamang naming magpadala ng webhooks sa https URLs. Kung nais mong i-configure ang local testing, tingnan ang sumusunod na seksyon.

Mga Kinakailangan sa Paghahatid ng Webhook

Para gumana nang normal ang iyong webhook at patuloy na makatanggap ng mga event:

  • Ang iyong server ay dapat tumugon gamit ang isang HTTP status code na mas mababa sa 400 (hal., 200 OK, 202 Accepted).
  • Anumang response na may status code na >= 400 ay ituturing na isang failed delivery.
  • Ang maraming magkakasunod na pagkabigo ay maaaring:
    • Magdulot ng pagkaantala o hindi maayos na pagkakasunod-sunod ng progress updates
    • Awtomatikong i-disable ang iyong webhook matapos ang paulit-ulit na mga pagtatangka (tingnan ang Auto-Disable Policy)

Tip: Palaging magbalik ng success response matapos mong i-validate at i-store ang webhook payload, kahit pa ang karagdagang pagproseso ay nangyayari nang asynchronous.

Pag-forward ng Webhooks para sa Local Testing

Kung nais mong subukan ang iyong webhook code nang lokal, na karaniwang nasa isang http address, maaari kang gumamit ng webhook proxy URL para i-forward ang webhooks papunta sa iyong computer o codespace. Ang mga sumusunod ay mga inirerekomendang hakbang gamit ang smee.io, pero maaari kang gumamit ng anumang serbisyo na gusto mong gamitin para makabuo ng webhook proxy URL.

Kumuha ng webhook proxy URL:

  1. Sa iyong browser, pumunta sa https://smee.io/
  2. I-click ang "Start a new channel"
  3. Kopyahin ang buong URL sa ilalim ng "Webhook Proxy URL". Gagamitin mo ang URL na ito sa mga sumusunod na hakbang sa setup.

I-forward ang webhooks:

  1. Kung wala ka pang na-install na smee-client, patakbuhin ang sumusunod na command sa iyong terminal.
npm install --global smee-client
  1. Para makatanggap ng mga na-forward na webhooks mula sa smee.io, patakbuhin ang sumusunod na command sa iyong terminal. Palitan ang WEBHOOK_PROXY_URL ng iyong webhook proxy URL mula kanina.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Makikita mo ang output na katulad nito, kung saan ang WEBHOOK_PROXY_URL ay ang iyong webhook proxy URL:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Panatilihin itong tumatakbo habang sinusubukan mo ang iyong webhook. Kapag gusto mong ihinto ang pag-forward ng webhooks, i-enter ang Ctrl+C.
    Tandaan na ang path ay /webhook at ang port ay 3000. Ang mga value na ito ay maaaring maging kapaki-pakinabang kapag gusto mong i-set up ang iyong sariling code para makatanggap ng webhook deliveries sa hinaharap.

Gumawa ng webhook:

Maaari mo na ngayong gamitin ang webhook proxy URL para gumawa ng bagong webhook sa Webhooks page.

Sample Response

Kapag nagbago ang status ng isang task, ang Meshy ay mag-POST ng webhook payload papunta sa iyong na-configure na URL. Ang payload ay naglalaman ng task object sa JSON format. Para sa kumpletong paglalarawan ng lahat ng properties ng task object at mga halimbawang payloads, tingnan ang: