ویب‌هوکونه او پېښې

د API نسخه 2026-10-affable-towhee

Lingara هغه څه چې ستاسو د حساب د لوست پلانونو او کارونې سره پېښېږي د پېښو په توګه ثبتوي، او ستاسو له لوبې یا اپ څخه پېښې مني. هره پېښه، په هره لاره چې ولاړه شي، یو شان لفافه لري، او د پېښو لېست ټولې یې شمېري.

لفافه

هره پېښه شپږ ساحې لري. id په lgr_evt_ پیلېږي، بې‌ساری دی، او هغه کیلي ده چې تکرارونه پرې لرې کېږي. type د پېښې نوم دی. created_at د پېښېدو وخت دی. api_version هغه نسخه ده چې data پرې جوړ شوی: هغه نسخه چې ستاسو پېرودونکی ورپورې تړل شوی، یا، په فیډ او جریان کې، هغه نسخه چې ستاسو غوښتنې په Lingara-Version کې نومولې. subject په lgr_sub_ پیلېږي او وايي چې پېښه د چا په اړه ده: ستاسو د پېرودونکي لپاره ثابت دی خو د هر پېرودونکي لپاره توپیر لري، او هېڅکله برېښنالیک، نوم یا د حساب پېژند نه دی. data کوچنی دی او سرچینې نوموي پرځای د دې چې کاپي یې کړي: هره سرچینه په هغه ساحه راواخلئ چې ورته اړتیا لري.

دوه ډولونه هر یو یوې جملې ته اړتیا لري. lesson_plan.ready کېدای شي د یوه پلان لپاره دوه ځله راشي، لومړی د data.status سره چې partial وي او بیا complete: د کارېدونکي پلان لپاره پر لومړي عمل وکړئ، یا د ټولو سېټونو لپاره complete ته انتظار وباسئ. usage.threshold_reached یوازې د کارونې په اندازه تادیه کوونکو حسابونو او پېرودونکو ته لېږل کېږي، او که کارونه په یو ځل له څو پولو تېره شي یوازې تر ټولو لوړه تېره شوې پوله راپور کېږي، نو د هرې پولې لپاره د یوې پېښې تمه مه کوئ.

یو ثبت، د اورېدو درې لارې

ویب‌هوکونه د هغه سرور لپاره مناسب دي چې عامه HTTPS پای‌ټکی لري. فیډ او جریان د هغه پروګرام لپاره مناسب دي چې هېڅ یې نه لري، لکه د لوبغاړي په ماشین کې یوه لوبه. لفافه په هره دروازه کې یو شان ده، نو یو پروګرام کولی شي په فیډ پیل وکړي او وروسته ویب‌هوکونو ته لاړ شي پرته له دې چې د پېښې د لوستلو طریقه بدله کړي. د پېښو لارې اصلي (native) پروګرامونو ته ځواب ورکوي. هغه لوبه چې په براوزر کې چلېږي لا نشي کولی هغوی ته غوښتنه وکړي، ځکه /v1/ هېڅ د بېلابېلو سرچینو مخکینۍ (preflight) غوښتنې ته ځواب نه ورکوي.

څوک پېښه اوري

یو پېرودونکی هغه وخت پېښه اوري چې events:read او د پېښې د ډول خپله ساحه ولري، چې لېست یې ښيي، او کله چې پېښه د پېرودونکي د څښتن په اړه وي. په فیډ او جریان کې، د لاسرسي د ټوکن ساحې دا نوره هم محدودوي، او types یې هغو ډولونو ته محدودوي چې تاسو یې نوموئ. webhook.test یوازې هغه پای‌ټکي ته ځي چې ورته لېږل شوی، هېڅکله فیډ ته نه، او ګډون پکې نشي کېدای. app.installed او app.uninstalled یوازې د اپ خپل پېرودونکي ته ځي، هېڅکله د همغه حساب بل پېرودونکي ته نه.

یو پای‌ټکی ثبت کړئ

پای‌ټکی د Lingara وېب اپ د ویب‌هوکونو په پاڼه کې ثبت کړئ، په app.getlingara.com/admin/webhooks کې، او لومړی پېرودونکی وټاکئ. د هغه URL باید https د 443 پر پورټ وکاروي، او کوربه یې باید یوازې عامه پتو ته حل شي. هغه پېښې وټاکئ چې ولېږل شي: یوازې هغه ډولونه وړاندې کېږي چې د پېرودونکي ساحې یې اجازه ورکوي. URL او پېښې وروسته نشي سمېدای: نوی پای‌ټکی ورزیات کړئ او زوړ ړنګ کړئ. د لاسلیک راز په lgr_whsec_ پیلېږي او یوازې یو ځل ښودل کېږي.

یو سپارل تایید کړئ

هر سپارل یو POST دی چې درې سرلیکونه لري، د Standard Webhooks د مشخصاتو سره سم: webhook-id (د پېښې id)، webhook-timestamp او webhook-signature. د HMAC کیلي د راز هغه برخه ده چې له lgr_whsec_ وروسته راځي او له base64 څخه ډیکوډ شوې، هېڅکله راز پخپله د متن په توګه نه. د بدنې له تجزیې مخکې، د هغې پر خامو بایټونو یې تایید کړئ، لکه لاندې. هغه سپارل رد کړئ چې د وخت مهر یې له اوسني وخت څخه تر پنځو دقیقو ډېر لرې وي، چې د Standard Webhooks د کتابتونونو ډیفالټ دی: دا د یوه نیول شوي سپارل د بیا لېږلو مخه نیسي.

signed   = webhook-id + "." + webhook-timestamp + "." + raw request body
key      = base64_decode(the secret after its prefix)
expected = "v1," + base64(hmac_sha256(key, signed))
accept   if |now - webhook-timestamp| <= 5 minutes
         and some entry of webhook-signature (space-separated) equals expected
             (compare in constant time)

Standard Webhooks د ډېرو ژبو لپاره تاییدوونکي خپروي. هغوی داسې راز ته تمه لري چې د whsec_ په بڼه وروسته له base64، یا یوازې base64 لیکل شوی وي، نو د Lingara د راز هغه برخه ورکړئ چې له lgr_whsec_ وروسته راځي. د Lingara خپل کتابتونونه ټول راز مني.

ژر ځواب ورکړئ، د بیا هڅو تمه ولرئ

په 10 ثانیو کې په هر 2xx ځواب ورکړئ، او کار وروسته وکړئ. هر بل څه، په شمول د وخت پای ته رسېدو یا 3xx (بیا لارښوونې نه تعقیبېږي)، د زیاتېدونکو وقفو سره د شاوخوا یوې ورځې لپاره بیا هڅه کېږي. د اتوماتیک سپارل په ځواب کې 410 پای‌ټکی سمدستي غیرفعالوي؛ د ازمېښت یا بیا سپارل په ځواب کې 410 داسې نه کوي. د پنځو ورځو ناکامو سپارلو وروسته هم پای‌ټکی غیرفعالېږي. په دواړو حالتونو کې یې څښتن ته برېښنالیک لېږل کېږي. د Lingara په خوا یوه تېروتنه هېڅکله د پای‌ټکي د غیرفعالولو لپاره نه شمېرل کېږي. د ویب‌هوکونو له پاڼې تاسو کولی شئ ازمېښت ولېږئ، یا د وروستیو 30 ورځو هر سپارل بیا وسپارئ. هر یو یوه هڅه ده، هېڅکله بیا نه تکرارېږي، او حتی غیرفعال پای‌ټکي ته هم لېږل کېږي.

سپارل لږ تر لږه یو ځل او بې‌ترتیبه دی. همغه پېښه کېدای شي دوه ځله راشي، او یوه بیا هڅه کېدای شي له وروستۍ پېښې وروسته راشي. webhook-id په هره بیا هڅه کې یو شان دی، او په بیا سپارل کې هم تر 30 ورځو وروسته پورې. هر id چې مو پروسس کړی د 30 ورځو لپاره ثبت کړئ، او تکرار له پامه وغورځوئ. که ترتیب مهم وي د created_at له مخې یې ترتیب کړئ.

د لاسلیک راز بدلول

یو پای‌ټکی کولی شي په یو وخت کې دوه د لاسلیک رازونه ولري. تر څو چې دواړه فعال وي، webhook-signature دوه v1, ننوتنې لري، او هغه اخیستونکی چې هر یو یې مني کار ته دوام ورکوي. نوی راز خپل سرور ته ورزیات کړئ، ځای پر ځای یې کړئ، بیا زوړ لغوه کړئ.

فیډ

GET /v1/events د یوه پېرودونکي د لاسرسي ټوکن سره items (لفافې)، next_cursor او has_more بېرته ورکوي. ټوکن events:read او د هر هغه ډول ساحې ته اړتیا لري چې غواړئ یې واورئ: یوازې د events:read سره فیډ تش دی. له اوس څخه پیلېږي. د شاوخوا وروستیو 30 ورځو د پېښو لپاره start=oldest ولېږئ. عامه پای‌ټکي او د لاسلیک راز ته اړتیا نه لري: د لاسرسي ټوکن ثابتوي چې څوک پوښتنه کوي. لاندې بدلونه هغه دواړه ساحې غواړي چې د لوست پلان پېښې ورته اړتیا لري.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=events:read lesson_plans:read" | jq -r '.access_token // error(.error)')"

curl "https://api.getlingara.com/v1/events" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

next_cursor تل شته: وې ساتئ او بېرته یې د cursor په توګه ولېږئ. دا ناڅرګند ارزښت دی. has_more د true سره معنا دا چې همدا اوس بیا غوښتنه وکړئ، او false معنا دا چې تاسو تر وروستي ځای رسېدلي یاست: وروسته بیا وګورئ، یا جریان پرانیزئ. له 30 ورځو زوړ کرسر د 410 او cursor_expired سره ردېږي. پرته له کرسر فیډ له اوس څخه پیلېږي، او تر منځ پېښې پرېښودل کېږي. د بېرته راوړلو لپاره یې د start=oldest سره غوښتنه وکړئ، چې تر هغه ځایه شاته ځي چې پېښې ساتل کېږي، او هغه id ارزښتونه پرېږدئ چې مخکې مو پروسس کړي.

جریان

GET /v1/events/stream همغه پېښې د server-sent events په توګه لېږدوي. د هر event چوکاټ data یوه لفافه ده، او د هر چوکاټ id: یو کرسر دی، د next_cursor همغه ارزښت، نو تاسو کولی شئ د فیډ او جریان ترمنځ پرته له کومې تشې واوړئ. د اړیکې له پرې کېدو، د done چوکاټ (جریان کله ناکله پخپله پای ته رسېږي) یا د error چوکاټ وروسته، د Last-Event-ID سره بیا وصل شئ چې وروستي ترلاسه شوي id: ته ټاکل شوی وي. ډېری SSE پېرودونکي دا ستاسو لپاره کوي، او د Lingara په کتابتونونو کې tailEvents هم (هلته streamEvents یوه یوازینۍ اړیکه ده). دا کرسر دی، نه د پېښې id. جریان د زړه ضربان (heartbeat) لېږي، نو چوپه اړیکه مړه اړیکه ده.

curl -N "https://api.getlingara.com/v1/events/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

Lingara ته پېښه ولېږئ

POST /v1/events د events:write سره Lingara ته د {type, data} په بڼه پېښه لېږي: world.context_changed (یو scene، source_lang، target_lang، level، او په اختیاري ډول یو npc د name او persona سره، او tags) یا world.practice_requested (یو topic او همغه ژبې او کچه). Idempotency-Key اړین دی: تر 255 پورې لیدل کېدونکي ASCII توري، لکه UUID. پرته له هغه ځواب 400 او idempotency_key_required دی. د هرې پېښې لپاره یې یو ځل وټاکئ، او په بیا هڅه کې همغه کیلي ولېږئ. یوه کیلي یوه پېښه ده: د یوې ورځې دننه، د همغې کیلي سره دویمه غوښتنه لومړی ځواب ترلاسه کوي (د JSON په توګه برابر، نه بایټ په بایټ)، حتی که بدنه یې توپیر ولري، او له هغه وروسته همغه پېښه ترلاسه کوي، لکه لاندې. راتلونکې پېښې لاسلیک نه کېږي: ستاسو د لاسرسي ټوکن ثبوت دی. نړۍ بیان کړئ، هېڅکله لوبغاړی نه: په scene، npc، topic یا tags کې هېڅ نوم یا چیټ مه اچوئ.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=events:write lesson_plans:write" | jq -r '.access_token // error(.error)')"

curl -X POST "https://api.getlingara.com/v1/events" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"world.context_changed","data":{"scene":"A night market in Taipei, just after rain","npc":{"name":"Auntie Lin","persona":"a street-food vendor who likes to haggle"},"source_lang":"en","target_lang":"zh","level":3,"tags":["market","food","chapter-2"],"generate":true}}'

د متن هره ساحه د لیدل کېدونکو تورو یوه کرښه ده، چې د دواړو خواوو تشو له لرې کولو وروسته شمېرل کېږي: scene او topic تر 160 پورې، npc.name تر 32 پورې، او npc.persona تر 120 پورې. د کرښې ماتېدنې، ټبونه او نور کنټرولي توري ردېږي، او همداراز نالیدونکي او د بڼې توري: د لوري بدلوونکي توري، صفر-پلن توري پرته له هغو نښلوونکو چې ځینې لیکدودونه او ایموجي ورته اړتیا لري، د ټګونو بلاک (tag block) او د شخصي کارونې توري. tags تر 8 پورې د کوچنیو تورو ماشیني نښې ساتي، هره یوه تر 24 تورو پورې، او هېڅکله د لوست پلان ته نه رسېږي. level له 1 څخه تر 9 پورې دی، او دواړه ژبې باید توپیر ولري. هغه غوښتنه چې له دې پولو بهر وي د 400 سره ردېږي او هېڅ پېښه نه ثبتوي.

د "generate": true سره (د world.practice_requested لپاره ډیفالټ)، ټوکن lesson_plans:write ته هم اړتیا لري. پرته له هغه غوښتنه د 403 سره ردېږي او هېڅ پېښه نه ثبتېږي. د هغه سره، Lingara د لوست یو پلان پیلوي، د همغو ازمېښتونو او همغه بیل سره لکه په مستقیم ډول یې جوړول، او د 202 ځواب reaction وايي چې څه وشول. د started او plan_status سره چې generating وي، یو lesson_plan.ready یا lesson_plan.failed چې data.plan_id یې د ځواب plan_id وي راځي، په هره دروازه چې تاسو یې کاروئ. د partial یا complete سره، پلان له کتابتون څخه راغلی او همدا اوس لوستل کېدای شي، او د هېڅ پېښې ژمنه نه کېږي: کېدای شي یوه یې بیا هم راشي، نو یوازې generating د انتظار وړ دی. د refused یا failed سره، پېښه لا هم پاتې ده. د همغې کیلي لاندې بیا هڅه نه کېږي، نو د بیا هڅې لپاره نوې پېښه ولېږئ.

د یوې ورځې دننه بیا هڅه لومړی ځواب بېرته ترلاسه کوي. له هغه وروسته بیا هڅه له ساتل شوې پېښې څخه بیا جوړېږي، چې هغه پلان ساتي چې پیل کړی یې دی خو دا نه چې غبرګون ولې رد شو. نو یوه ناوخته بیا هڅه کېدای شي د reaction سره چې failed او internal وي ځواب ورکړي: معنا دا چې لومړۍ پایله نه ده ثبت شوې، نه دا چې پلان شتون نه لري. که مو plan_id ساتلی وي پلان پرې ولولئ، یا نوې پېښه ولېږئ.

Tidewater Games: یوه لوبه پرته له سرور

Tidewater Games، یو خیالي سټوډیو، د Godot یوه لوبه جوړوي چې په هغې کې لوبغاړی د شپې یو بازار ګوري. د هغې جوړوونکی لوبه پر خپل ماشین، د خپل پېرودونکي سره چلوي.

لوبغاړی د نوډلز یوې غرفې ته ننوځي. لوبه world.context_changed د "generate": true سره لېږي، همغه امر چې پورته د راتلونکو پېښو په برخه کې راغلی، او د ځواب plan_id ساتي.

که plan_status د generating وي، لوبه جریان لولي، یا فیډ بیا بیا ګوري، تر څو چې د همغه plan_id سره یو lesson_plan.ready راشي. بیا پلان د lesson_plans:read سره لولي، لکه لاندې. که پلان دمخه complete و، سمدستي یې لولي.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:read" | jq -r '.access_token // error(.error)')"

curl "https://api.getlingara.com/v1/lesson-plans/$ID" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

وروسته سټوډیو یو کوچنی سرور د HTTPS پای‌ټکي سره ورزیاتوي او د lesson_plan.ready لپاره یې ثبتوي. همغه پېښه، د همغه id سره، هلته رسېږي، او د لوبې کوډ د هغې د لوستلو لپاره نه بدلېږي.

د پېرودونکي راز باید هېڅکله د لوبې په جوړښت کې ونه لېږدول شي، ځکه هر څه چې د لوبغاړي په وسیله وي لوستل کېدای شي. تر هغه چې Lingara د لوبغاړي په استازیتوب ننوتل ملاتړ نه کړي، د لوبغاړو پر ماشینونو لوبه له خپل سرور سره خبرې کوي، او یوازې د جوړوونکي خپله کاپي په مستقیم ډول له Lingara سره خبرې کوي.

پېښې څومره لګښت لري

ستاسو د پېرودونکي کارونه هره منل شوې راتلونکې پېښه، د فیډ هره غوښتنه او هر پرانیستل شوی جریان شمېري، لکه څنګه چې د /v1/ هره غوښتنه شمېري. هغه پېښه چې د "generate": true سره لېږل شوې وي د لوست د پلان په توګه هم شمېرل کېږي. د ویب‌هوک هر سپارل د هرې پېښې او هر پای‌ټکي لپاره یو ځل شمېرل کېږي، په لومړي 2xx کې، هره هڅه چې وي. هېڅکله بیا نه شمېرل کېږي، او ازمېښت هېڅکله نه شمېرل کېږي. GET /v1/usage تر اوسه پورې میاشت ښيي.

که یوه ژباړه له انګلیسي مرجع سره توپیر ولري، انګلیسي مرجع سمه ده.