Агуулгыг алгасах

Локал webhook

Өөрийн компьютер дээр ажиллаж буй backend руу webhook хүлээж авч, гарын үсгийн шалгалтаа турших. Хугацаа: 15 минут. Хэрэгтэй: localhost дээрх webhook handler, tunnel хэрэгсэл (cloudflared эсвэл ngrok), консолд апп.

Яагаад tunnel хэрэгтэй вэ

Платформ webhook-ийг зөвхөн нийтийн https:// хаяг руу илгээнэ:

  • URL нь https://, ≤ 2048 тэмдэгт;
  • холбогдох IP-г DNS-ийн дараа шалгана — дотоод сүлжээ (10.x, 192.168.x …), loopback (127.0.0.1, localhost), link-local хаяг руу холбогдохгүй (refused: not a public address гэж хүргэлтэд бичигдэнэ);
  • redirect (3xx) дагахгүй — 3xx нь амжилтгүй хүргэлт.

Тиймээс http://localhost:3000 руу шууд илгээх боломжгүй; нийтийн https хаягтай tunnel хэрэглэнэ.

Алхам

  1. Handler-аа локалаар асаана (жишээ нь POST http://localhost:3000/webhooks/gerege), түүхий body-оор гарын үсэг шалгадаг байх (Гарын үсэг шалгах).

  2. Tunnel нээнэ:

    # Cloudflare (бүртгэлгүй, түр хаяг)
cloudflared tunnel --url http://localhost:3000
# → https://<random>.trycloudflare.com

# эсвэл ngrok
ngrok http 3000
# → https://<random>.ngrok-free.app

  3. Консолд апп → «Webhook endpoint» → test орчинд шинэ endpoint: URL https://<random>.trycloudflare.com/webhooks/gerege, хүсвэл event-ийн шүүлтүүр. Хариунд whsec_… secret нэг удаа харагдана — handler-ийн орчны хувьсагчид хадгална. API: POST /api/v1/miniapp/dev/apps/{id}/webhook-endpoints {"environment": "test", "url": "…", "description": "laptop tunnel", "event_types": []} → 201 {"endpoint", "webhook_secret", "notice"} (event_types хоосон = бүгд). Test endpoint нь live event хэзээ ч авахгүй — live-ийн endpoint-д хүрэхгүй.

  4. Тест илгээх: POST /api/v1/miniapp/dev/apps/{id}/webhook-endpoints/{eid}/test — гарын үсэгтэй webhook.test-ийг тэр endpoint руу тэр дор нь илгээж {event_id, endpoint_id, ok, status_code, error, duration_ms, delivery} хариулна. ok: true бол бодит event-ийн зам ажиллаж байна (ижил signer, ижил secret). Минутад 20 удаа.
  5. Бодит event үүсгэнэ — Утасгүй турших-ын симуляц, эсвэл test түлхүүрээр intent үүсгэж цуцлах.
  6. Консолын «Хүргэлтүүд» (GET /api/v1/miniapp/dev/apps/{id}/webhook/deliveries?endpoint_id=…) — event бүрийн төлөв (pending, delivered, failed, skipped), оролдлого, сүүлийн HTTP код, алдаа, body. Handler-аа засаад «Дахин илгээх» (POST …/webhook/deliveries/{event_id}/retry?endpoint_id=…) — event анхны body-оор, шинэ t-тэй гарын үсгээр дахин ирнэ.
  7. Дууссаны дараа test endpoint-оо устгах эсвэл PATCH {"status": "disabled"} — tunnel-ийн түр хаяг үхсэн endpoint 5 хоног амжилтгүй бол автоматаар auto_disabled болж, байгууллагын админуудад мэдэгдэл очно.

Анхаарах зүйл

  • Secret солих: POST …/webhook-endpoints/{eid}/rotate-secret — шинэ whsec_…, хуучин нь 24 цаг хамт гарын үсэг зурна (event бүрт хоёр v1). Tunnel-ийн хаяг өөрчлөгдвөл PATCH {"url": "…"} — secret хэвээр.
  • Апп-ын анхны webhook (endpoint №1, POST …/webhook {"url"}) нь test ба live хоёуланд нэг URL. Live апп-ын тэр URL-ийг локал tunnel руу бүү чиглүүл — test-д тусдаа endpoint нэм. Хуучин POST …/webhook дуудлага бүр шинэ secret олгодог хэвээр.
  • Review-д байгаа эсвэл түдгэлзсэн апп-ын endpoint №1-ийн URL/secret-ийг өөрчлөх боломжгүй (409 locked_for_review).
  • Endpoint идэвхгүй (disabled, auto_disabled) үед хүргэх ээлж ирсэн event skipped — алдсан event-ээ Events API-аас татна.
  • Нийтийн «request bin» сайтууд (webhook.site г.м.) event-ийн бүх body-г гуравдагч этгээдэд харуулна — live өгөгдөлд хэзээ ч бүү хэрэглэ; өөрийн tunnel-ээ хэрэглэ.
  • 2xx-ийг 10 секундэд буцаана; удаан ажлыг queue-д. Debugger-ийн breakpoint дээр зогсвол хүргэлт timeout болж retry хуваарьт орно (Хүргэлт ба давталт).