Хүргэлт ба давталт¶
Event хэзээ, хэдэн удаа, ямар дарааллаар ирэх, юуг амжилт гэж тооцох, удаан ажиллахгүй байгаа endpoint юу болох, алдсан event-ийг яаж буцааж авахыг энд бичив. Endpoint-оо production-д гаргахаас өмнө 5 минут зарцуулж уншина уу.
- Хэрэгтэй: ажиллаж буй webhook endpoint (Тойм), гарын үсэг шалгадаг handler (Гарын үсэг).
1. Товчоор¶
- Амжилт = 10 секундэд 2xx. Бусад бүх зүйл (3xx, 4xx, 5xx, timeout, холболтын алдаа) — амжилтгүй, дахин оролдоно.
- Дор хаяж нэг удаа (at-least-once): нэг event нэг endpoint руу хоёр ба түүнээс олон удаа ирж болно.
id-аар давхардлыг арилга. - Дараалал баталгаагүй.
payment_intent.succeededньpayment_intent.claimed-ээс өмнө ирж болно. Объектынstatus-аар шийд, ирсэн дарааллаар биш (Idempotent handler). - Endpoint бүр тусдаа: event нь тухайн орчны, шүүлтүүрт нь таарсан идэвхтэй endpoint бүрт өөрийн хүргэлттэй (оролдлого, retry, төлөв). Нэг endpoint унасан нь нөгөөдөө нөлөөлөхгүй.
- Event commit хийгдмэгц шууд илгээгдэнэ; амжилтгүй бол retry хуваарийн дагуу ~2 хоног, дараа нь
failed. Endpoint 5 хоног дараалан бүтэлгүйтвэл автоматаар унтарна. Алдсан бүхнийг Events API-аас татна.
2. Хэзээ илгээгдэх¶
- Өөрчлөлт (төлбөр, claim, буцаалт …) өгөгдлийн санд commit хийгдэх тэр transaction-д event outbox-д бичигдэж, мөн тэр transaction-д тухайн орчны идэвхтэй, шүүлтүүрт нь таарсан endpoint бүрт хүргэлт үүснэ — өөрчлөлт болсон бол event заавал бий, болоогүй бол байхгүй. Тэр агшинд endpoint-гүй байсан ч event хадгалагдаж Events API-д харагдана.
- Шууд оролдлого. Payment intent-ийн төлөв өөрчлөгдөх, claim, буцаалт, симуляц, консолын «дахин илгээх»-ийн
дараа тэр дор нь нэг удаа илгээнэ (вендинг машин
requires_capture-ийг минут хүлээх ёсгүй). Энэ нь хамгийн боломжоор (best effort): процесс дотор зэрэг 8 хүртэл; ачаалал их бол job-д үлдээнэ — алдагдахгүй, минут хоцорно. - Job минут тутам хугацаа нь болсон хүргэлтүүдийг (нэг удаад 50-аар) илгээнэ. Шууд оролдлого ба job нэг хүргэлтийг хэзээ ч нэгэн зэрэг илгээхгүй (lease).
app.status_changed,consent.revoked,settlement.paidболон консолын «тест төлбөр»-ийн баталгаажуулалтын (…/test-intents/{pi}/confirm) event шууд оролдлогогүй — job-оор, 1 минутын дотор ирнэ.
3. Хүсэлт ба хариу¶
POST, body нь event үүсэх үед нэг удаа бичигдсэн JSON — retry бүрт, endpoint бүрт яг тэр byte. Толгой бүрт шинэt-тэй, тухайн endpoint-ийн secret-ээр зурсан гарын үсэг (Гарын үсэг).- Timeout 10 секунд (холболт 5 с, TLS 5 с). Ажлаа queue-д хийж 2xx-ыг шууд буцаа.
- Redirect дагахгүй: 301/302/307 нь амжилтгүй гэж бүртгэгдэнэ. URL-аа эцсийн хаягаар нь тохируул.
- Хариуны body-г уншихгүй (эхний 64 KiB-ийг хаяад орхино) — юу ч буцааж болно,
204хангалттай. - Хаяг нь DNS-ийн дараа шалгагдана: дотоод сүлжээ, loopback, link-local хаяг руу хэзээ ч илгээхгүй («refused: not a public address»).
- Гарын үсэггүй event хэзээ ч илгээгдэхгүй: платформ secret-ээ нээж чадаагүй бол хүргэлт хүлээж, retry шиг дахин оролдоно (энэ нь таны endpoint-ийн «амжилтгүй» гэж тооцогдохгүй).
4. Retry хуваарь¶
| Оролдлого | Өмнөх амжилтгүйгээс хойш |
|---|---|
| 1 | шууд (эсвэл дараагийн минутын job) |
| 2 | 1 минут |
| 3 | 5 минут |
| 4 | 30 минут |
| 5 | 2 цаг |
| 6 | 6 цаг |
| 7 | 12 цаг |
| 8 | 24 цаг |
Нийт 8 оролдлого, эхнийхээс сүүлийнх хүртэл ойролцоогоор 45 цаг (~2 хоног). 8 дахь нь бүтэлгүйтвэл тэр хүргэлт
failed болж дахин автоматаар илгээгдэхгүй. Хугацаа нь job-ийн минутын давтамжаар нэг минут хүртэл хоцорч болно.
5. Ажиллахгүй endpoint — анхааруулга ба автомат унтраалт¶
Endpoint-ийн хүргэлт бүр бүтэлгүйтэж эхэлсэн мөчөөс (failing_since) дараалсан амжилтгүйг тоолно; нэг ч амжилттай
хүргэлт (хоцорсон ч) тоолуурыг тэглэнэ. Шалгалт 15 минут тутам:
| Хугацаа | Юу болох |
|---|---|
| 24 цаг бүгд амжилтгүй | Байгууллагын админуудад нэг удаа мэдэгдэл «Webhook ажиллахгүй байна» (апп-ын нэр, орчин — URL биш) |
| 5 хоног бүгд амжилтгүй | Endpoint auto_disabled болж, disabled_reason-тэй; түүнд хүлээгдэж байсан хүргэлтүүд skipped; админуудад «Webhook унтарлаа» |
Дахин асаах: endpoint-оо засаад, алдсан event-ээ Events API-аас татаад, PATCH …/webhook-endpoints/{eid}
{"status": "active"} — тоолуур шинээр эхэлнэ. Унтарсан хугацааны event-үүд тэр endpoint руу автоматаар илгээгдэхгүй;
хэрэгтэй бол консолоос «дахин илгээх».
6. Хүргэлтийн төлөв, хадгалалт, консол¶
status |
Утга |
|---|---|
pending |
Илгээх ээлж хүлээж байна (эсвэл retry хийгдэнэ) |
delivered |
2xx авсан |
failed |
8 оролдлого бүгд бүтэлгүйтсэн |
skipped |
Хүргэх ээлж нь ирэхэд endpoint унтарсан байсан; консолын жагсаалтад — тэр агшинд нэг ч endpoint-д хамаараагүй event. Дахин автоматаар илгээгдэхгүй |
- URL ба secret нь хүргэх агшинд уншигдана: URL-аа сольвол хуучин event-ийн дараагийн retry шинэ URL руу явна. Endpoint-оо устгавал түүний хүргэлтүүд хамт устна.
- Event үүссэнээс хойш 30 хоног хадгалагдаад устна (хүлээгдэж буй хүргэлттэй нь хүргэлт дуустал үлдэнэ) — Events API-аар ч 30 хоногийг л татна.
Хөгжүүлэгчийн консолын апп-ын «Webhook хүргэлтүүд» (Хөгжүүлэгчийн sandbox):
- Хүргэлтийн жагсаалт шинээс нь —
status, орчин (test/live),type,endpoint_id-аар шүүнэ: оролдлогын тоо, сүүлийн HTTP код ба алдаа, дараагийн оролдлогын цаг, body, endpoint бүрийн хүргэлт (deliveries[]). Нэг event-ийгGET /dev/apps/{id}/webhook/events/{event_id}-ээр. - «Дахин илгээх» (
POST …/webhook/deliveries/{event_id}/retry[?endpoint_id=]) — дурын event-ийг (failed,skipped,deliveredч) шинэ retry мөчлөгтэй (оролдлого 0-ээс) тэр дор нь илгээнэ:endpoint_id-тай бол тэр endpoint руу (ижил орчных — эс бөгөөс409 environment_mismatch), үгүй бол event-ийн бүх хүргэлтийг дахин (хүргэлтгүй байсан бол одоогийн идэвхтэй, шүүлтүүрт таарах endpoint-уудад). Endpoint алга бол409 no_webhook. webhook.test— гарын үсэгтэй тест event-ийг бодит event-ийн замаар тэр дор илгээгээд үр дүнг (ok,status_code,error,duration_ms) харуулна:POST …/webhook/testнь endpoint №1 руу (эсвэл эхний endpoint),POST …/webhook-endpoints/{eid}/testнь сонгосон endpoint руу (шүүлтүүр, төлөвөөс үл хамааран). Амжилтгүй бол бусдын адил retry хийгдэнэ. Минутад 20.