Webhooks

Webhooks គឺជាវិធីមួយដែលកម្មវិធីអាចផ្ញើសារឬព័ត៌មានដោយស្វ័យប្រវត្តិទៅកាន់កម្មវិធីផ្សេងទៀត។ ជាមួយនឹងមុខងារ webhooks របស់ FormKH អ្នកអភិវឌ្ឍន៍ទាំងអស់អាចទទួលបានការឆ្លើយតបពីអ្នកឆ្លើយតបក្នុងពេលជាក់ស្តែង ដោយប្រើ webhook URL របស់ពួកគេ។

ហេតុអ្វីបានជាដាក់បញ្ចូល(intergrate)ជាមួយ webhooks?

ណែនាំសម្រាប់៖

• ទម្រង់បែបបទដែលមានការឆ្លើយតបច្រើន

• ប្រព័ន្ធផ្ទៃក្នុង / លំហូរការងារដែលត្រូវការការរួមបញ្ចូលជាមួយនឹងការប្រមូលទិន្នន័យទម្រង់បែបបទ

• អ្នកបង្កើតកម្មវិធីដែលមានជំនាញព័ត៌មានវិទ្យា ដែលមានសមត្ថភាពប្រើប្រាស់ឧបករណ៍អភិវឌ្ឍន៍កម្មវិធីរបស់យើង ដើម្បីរៀបចំចំណុចបញ្ចប់អ៊ីនធឺណិតសម្រាប់ការទទួលទិន្នន័យឆ្លើយតប

មិនណែនាំប្រសិនបើ៖

• អ៊ីម៉ែល ឬបញ្ជី Excel អាចផ្ទុកការឆ្លើយតបនៃទម្រង់បែបបទបានគ្រប់គ្រាន់។

តើ Webhooks មានសុវត្ថិភាពទេ?

បាទ/ចាស, ទិន្នន័យរបស់អ្នកត្រូវបានអ៊ិនគ្រីប។ ឧបករណ៍អភិវឌ្ឍន៍កម្មវិធីរបស់យើង (SDK) ផ្តល់ការណែនាំអំពីការដំឡើងប្រព័ន្ធទទួលរបស់អ្នកទៅ៖

• ផ្ទៀងផ្ទាត់ថាការបញ្ជូននីមួយៗត្រូវបានផ្ញើដោយ FormKH ហើយមិនមែនជាម៉ាស៊ីនមេផ្សេងទៀតទេ។

• ឌិគ្រីបការបញ្ជូនដោយប្រើសោសម្ងាត់ដែលមានតែអ្នកជាម្ចាស់ប៉ុណ្ណោះ។

ការដំឡើង Webhooks (សម្រាប់អ្នកអភិវឌ្ឍន៍)

សុពលភាព៖ អាសយដ្ឋាន IP

• Production: X.X.X.X (form.gov.kh)

• Staging: X.X.X.X (staging.form.gov.kh )

ឥឡូវនេះយើងកំពុងប្រើប្រាស់ NAT Gateways (ឯកសារ) សម្រាប់ចរាចរណ៍ចេញក្រៅរបស់យើងទាំងអស់ពី FormKH ដើម្បីធានាថាការហៅតាម webhook ទាំងអស់ដែល FormKH បង្កើតនឹងត្រូវបានគេមើលឃើញថាមានប្រភពចេញពី IPs មួយក្នុងចំណោម 3 IPs ដែលយើងរដាក់។

ក) ការដំឡើង Webhooks តម្រូវការជាមុន៖ ចំណុចបញ្ចប់ HTTPS ត្រូវតែបង្ហាញនៅលើអ៊ីនធឺណិត។

1. ការរៀបចំប្រព័ន្ធរបស់អ្នកក្នុងការទទួល ផ្ទៀងផ្ទាត់ និងឌិគ្រីបការឆ្លើយតបទម្រង់បែបបទ៖

• កំណត់រចនាសម្ព័ន្ធទម្រង់ Webhook URL៖ យើងសន្មត់ថាអ្នកចង់បង្កើតទម្រង់បែបបទថ្មី និងកំណត់រចនាសម្ព័ន្ធ webhooks សម្រាប់ទម្រង់បែបបទរបស់អ្នក។ ដើម្បីសម្រេចបាន អ្នកត្រូវធ្វើតាមជំហានខាងក្រោម។

1. ចូលទៅកាន់ផ្ទាំងគ្រប់គ្រង។

2. បង្កើតទម្រង់បែបបទថ្មីដោយបំពេញព័ត៌មានដែលត្រូវការទាំងអស់។ រួចរក្សាទុកសោសម្ងាត់។

3. ចូលទៅកាន់ផ្ទាំងការកំណត់។

4. នៅផ្នែកខាងឆ្វេង សូមចុចផ្ទាំង Webhooks ។

5. ដាក់បញ្ចូល URL របស់ webhook របស់អ្នកក្នុងប្រអប់។ អ្នកក៏មានជម្រើសដើម្បីបើកការព្យាយាមម្តងទៀតផងដែរ។

អ្នកនឹងឃើញការឆ្លើយតបដែលអ្នកឆ្លើយតបបានបំពេញនៅ៖

• ចុចលើប៊ូតុងចែករំលែក ហើយចែករំលែកតំណជាមួយអ្នកឆ្លើយតប។

• នៅពេលអ្នកប្រើប្រាស់ចុច បញ្ជូន បន្ទាប់ពីបំពេញទម្រង់បែបបទ អ្នកអាចឃើញការឆ្លើយតបដែលបានផ្ញើទៅអ្នកតាមរយៈ URL របស់ webhook ដែលអ្នកបានកំណត់រចនាសម្ព័ន្ធ។

នេះជារចនាសម្ព័ន្ធនៃការឆ្លើយតបដែលអ្នកនឹងទទួលបាន៖

POST /test HTTP/1.1
Host: your.webhookurl.com
Connection: close
Accpt: application/json, text/plain, */*
Accept-Encoding: gzip, compress, deflate, br
Connection: close
Content-Length: 481
Content-Type: application/json
Traceparent: 00-000000000000000025a579dca46fd06f-20121788faa8e6d0-01
Tracestate: dd=t.dm:-0;s:1
User-Agent: axios/1.4.0
X-Datadog-Parent-Id: 2310935435882850000
X-Datadog-Sampling-Priority: 1
X-Datadog-Tags: _dd.p.dm=-0
X-Datadog-Trace-Id: 2712708339119149167
X-Formkh-Signature: t=1692605192031,s=64e31b083c2273003b2cc16e,f=64d32dfb6daaeb00dad1d9f4,v1=Pwiytmuns/zc3ezrfQ9EX473330JUYCD/M/XDzv3zN78B0ySkTlwIfJEcwGQsLUjxqqgs9vU3aGDIGToFlEKBA==

{
"data": {
"formId": "64d32dfb6daaeb00dad1d9f4",
"submissionId":"64e31b083c2273003b2cc16e",
"encryptedContent":"NkzUYaxT0yCvLkQmFV7wivoLC1UjVUAjAUeuz8gDMVw=;TR8pN7FJXp8JyIhaHjb503spWfW9mpcu:9r1mzCV55oUov7PuvV244Qkjwl9LMq0xmQ5gg9cLxXUyasmbaF1CMLCynJaBYZcyUrjN+MRcqmgrhfy6/NxdWN6sH4+bcOo9oyeerUNgZeeVydQbG6PPQAnwaKcumLvUsvIlVa+jbhd/sOPKck2pLvr/rjZ2mfSTg3G/UiSf6RgLZHlNgT0Me0Ytb1YkBH3MGKiKU4OtD4+kIBdK8MUUxQwh",
"version":1,
"created":"2023-08-21T08:06:32.029Z",
"attachmentDownloadUrls":{
"64f017bcf1f7b50046b5db04": "http://localhost:4566/local-attachment-bucket/64f01627f1f7b50046b5da0c/e23a02cdd403fa5fb721d8117132b8df84428fbd/b8bb529ff4368809d97e3a478b8b31eda87b0797cd535dd3155353d080a78d70?AWSAccessKeyId=fakeKey&Expires=1693466012&Signature=B0K85Yoqcy2Ly%2FZUf9tT%2BIowTS4%3D",
}
}
}

1. ដំណើរការទិន្នន័យទាញយកដោយ Webhooks៖

ជាមួយនឹងការឆ្លើយតបខាងលើ អ្នកនឹងសម្គាល់ឃើញថាខ្លឹមសារនៃការឆ្លើយតបរបស់អ្នកប្រើប្រាស់ត្រូវបានអ៊ិនគ្រីប។ មានតែទិន្នន័យមេតាមួយចំនួនប៉ុណ្ណោះដែលត្រូវបានផ្ញើជាអត្ថបទធម្មតា។ ដូច្នេះ យើងត្រូវតែឌិគ្រីប ដើម្បីមើលខ្លឹមសារជាក់ស្តែង។ FormKH ផ្តល់ជាកញ្ចប់ npm @formkh/formkh-javascript-sdk ដែលផ្តល់ឱ្យអ្នកនូវមុខងារមួយចំនួនដើម្បីដំណើរការមាតិកាដែលបានអ៊ិនគ្រីបដែលបានផ្ញើពី FormKH ទៅកាន់អ្នក។ ដើម្បីឌិគ្រីបមាតិកា អ្នកអាចធ្វើដូចខាងក្រោម៖

• នៅក្នុងគម្រោងរបស់អ្នក បង្កើតឯកសារ .npmrc ហើយដាក់មាតិកានៅក្នុងនោះ @formkh:registry=https://git.anakotlab.com/api/v4/projects/97/packages/npm/

• ដំឡើងកញ្ចប់ @formkh/formkh-javascript-sdk ដោយប្រើ command ៖ npm i @formkh/formkh-javascript-sdk

• ដាក់កញ្ចប់ទៅក្នុងឯកសារ js/ts របស់អ្នក ហើយប្រើវា៖

// This example uses Express to receive webhooks
const express = require('express')
const app = express()

// Instantiating formsg-sdk without parameters default to using the package's
// production public signing key.
const formkhPackage = require("@formkh/formkh-javascript-sdk")({
mode: process.env.NODE_ENV,
webhookSecretKey: process.env.SIGNING_SECRET_KEY,
});

// This is where your domain is hosted, and should match
// the URI supplied to FormSG in the form dashboard
const PORT_URI = "https://your-domain.com/submissions"

// The secret key of the form that you saved when creating the form
const formSecretKey = process.env.FORM_SECRET_KEY;

// Set to true if you need to download and decrypt attachments from submissions
const HAS_ATTACHMENTS = false

app.post(
"/submissions",
// Endpoint authentication by verifying signatures
function (req, res, next) {
try {
formkhPackage.webhooks.authenticate(
req.get("X-FormKH-Signature"),
POST_URI
);
// Continue processing the POST body
return next();
} catch (e) {
return res.status(401).send({ message: "Unauthorized" });
}
},
// Decrypt the submission
express.json(),
// Decrypt the submission
async function (req, res, next) {
// If `verifiedContent` is provided in `req.body.data`, the return object
// will include a verified key.
const submission = HAS_ATTACHMENTS
? await formkhPackage.crypto.decryptWithAttachments(
formSecretKey,
req.body.data
)
: formkhPackage.crypto.decrypt(formSecretKey, req.body.data);

// If the decryption failed, submission will be `null`.
if (submission) {
// Continue processing the submission
return res.send({ submission });
} else {
// Could not decrypt the submission
return res.status(500).send({ message: "Internal Server Error" });
}
}
);

app.listen(8080, () => console.log('Running on port 8080'))

ចំណាំ៖ សម្រាប់ព័ត៌មានលម្អិតអំពីការប្រើប្រាស់ webhook សូមមើល gitlab នៃ formkh-javascript-sdk។ 3. ធ្វើតេស្តលើការឆ្លើយតបដែលត្រូវបានទទួលនៅ URL ចំនុចបញ្ចប់របស់អ្នក។ ប្រសិនបើប្រព័ន្ធ IT របស់អ្នកត្រឡប់លេខកូដឆ្លើយតប HTTP-2xx នោះ webhook ត្រូវបានគេចាត់ទុកថាទទួលបានជោគជ័យ។ កំណត់សម្គាល់សំខាន់៖

• សូមចាក់សោកំណែ SDK ដែលអ្នកកំពុងប្រើ ហើយបិទការអាប់ដេតដោយស្វ័យប្រវត្តិ ដើម្បីជៀសវាងការរំខានពីការបំបែកការផ្លាស់ប្តូរ។

• អ្នកទទួលខុសត្រូវក្នុងការរៀបចំប្រព័ន្ធរបស់អ្នកឱ្យបានត្រឹមត្រូវ ដើម្បីទទួលបាន ផ្ទៀងផ្ទាត់ និងឌិគ្រីបការឆ្លើយតបទម្រង់បែបបទដោយប្រើ SDK របស់យើង។ FormKH មិនទទួលខុសត្រូវចំពោះការដំឡើងរបស់អ្នកទេ លើកលែងតែក្នុងការធានាថាម៉ាស៊ីនមេរបស់យើងកំពុងកំណត់ផ្លូវឆ្លើយតបយ៉ាងត្រឹមត្រូវស្របតាម SDK របស់យើង។

• ភ្នាក់ងារភាគច្រើនបញ្ជាក់ការហៅតាម webhook របស់ FormKH ដោយផ្អែកលើបន្ទុក និងហត្ថលេខា។ ប្រសិនបើអ្នកត្រូវការបញ្ជាក់ការហៅតាម webhook ដោយដាក់ក្នុងបញ្ជីស IP សូមមើលផ្ទាំង "សុពលភាព៖ អាសយដ្ឋាន IP"។

ខ) បើកការព្យាយាម Webhook ម្តងទៀត ប្រសិនបើអ្នកបើក "បើកការព្យាយាមម្តងទៀត" នៅក្នុងការកំណត់ ទម្រង់នឹងផ្ញើ webhooks ឡើងវិញ ប្រសិនបើប្រព័ន្ធ IT របស់អ្នកបរាជ័យក្នុងការទទួលវា។ ដើម្បីទទួលបាន webhook ម្ដងទៀតដោយសុវត្ថិភាព ប្រព័ន្ធរបស់អ្នកគួរតែត្រូវបានរចនាឡើងដើម្បីដោះស្រាយ webhooks ស្ទួន out-of-order delivery ការបញ្ជូន និងការដាក់ស្នើដែលមិនមែនជាពេលវេលាពិត ទោះបីទម្រង់បែបបទនេះលែងដំណើរការក៏ដោយ។

webhook នឹងត្រូវបានព្យាយាមជាលើកដំបូងភ្លាមៗបន្ទាប់ពីទម្រង់ត្រូវបានដាក់ស្នើ។ ប្រសិនបើការព្យាយាមលើកដំបូងបរាជ័យ នោះ webhook នឹងត្រូវបានព្យាយាមម្តងទៀតរហូតដល់ 6 ដង ក្នុងរយៈពេល 24 ម៉ោងបន្ទាប់ នៅចន្លោះពេលខាងក្រោមចាប់ពីពេលដាក់ស្នើ៖

• 5 ± 1 នាទី

• 60 ± 15 នាទី

• 2 ± 0.5 ម៉ោង

• 4 ± 1 ម៉ោង

• 8 ± 2 ម៉ោង

• 20 ± 4 ម៉ោង

ការព្យាយាមម្តងទៀតនឹងឈប់នៅពេលដែល webhook ទទួលបានជោគជ័យ។ ប្រសិនបើប្រព័ន្ធរបស់អ្នកបរាជ័យក្នុងការទទួលបានការព្យាយាមម្តងទៀតចុងក្រោយ 16-24 ម៉ោងបន្ទាប់ពីទម្រង់ត្រូវបានដាក់ស្នើនោះ webhook នឹងមិនត្រូវបានព្យាយាមទៀតទេ។ អ្នកនៅតែអាចទាញយកទិន្នន័យដាក់ស្នើនៅក្រោមផ្ទាំងទិន្នន័យ។