Dadansoddi
Danfoniadau wedi’u llofnodi, ac e-bost nad yw’n dweud dim.
Mae webhook yn postio pob ymateb newydd i URL https o’ch dewis. Mae pob
danfoniad yn cario pennyn X-NumoForms-Signature:
sha256= ac yna HMAC-SHA256 o union gorff y cais, wedi’i
gyfrifo â chyfrinach sy’n unigryw i’r webhook hwnnw, fel y gall eich pwynt
terfyn brofi mai gennym ni y daeth y llwyth. Ar wahân i hynny, cewch
hysbysu cyfeiriadau e-bost o’ch dewis pan fydd ymateb yn cyrraedd — ac nid
yw’r e-byst hynny’n cynnwys unrhyw atebion, yn fwriadol.
Beth sy’n cyrraedd eich pwynt terfyn
Un POST JSON fesul ymateb. Mae’r corff yn dal pum maes a dim byd arall, felly cewch ysgrifennu dosrannwr ar ei gyfer heb ddyfalu.
| Maes | Beth mae’n ei ddal |
|---|---|
event | response.created |
survey_id | Yr arolwg y mae’r ymateb yn perthyn iddo. |
response_id | Dynodydd unigryw yr ymateb hwn. |
created_at | Pryd y cofnodwyd yr ymateb. |
answers | Yr atebion, gyda dynodydd y cwestiwn yn allwedd. |
| Pennyn | At ba ddiben |
|---|---|
X-NumoForms-Event | Enw’r digwyddiad. Dim ond un sydd heddiw: response.created. |
X-NumoForms-Signature | sha256= ac yna HMAC-SHA256 o union gorff y cais, mewn hecs. |
X-NumoForms-Delivery | Dynodydd unigryw i’r ymgais ddanfon hon, fel y gallwch adnabod dyblyg. |
Caiff y danfon ei danio gan sbardun cronfa ddata ar y tabl ymatebion, nid gan sgrin benodol yn y rhaglen. Mae hynny’n bwysicach nag y mae’n swnio: mae ymatebion a gyflwynir drwy ffurflen wedi’i mewnosod, drwy ddolen wedi’i chynnal, neu drwy ymateb rhannol a ailddechreuwyd ddyddiau’n ddiweddarach drwy gadw a pharhau, i gyd yn dilyn yr un llwybr, felly nid oes llwybr yr anghofiwyd gennym ei gysylltu.
Mae’r webhook yn tanio pan fydd yr ymateb yn cyrraedd. Os ydych wedi galluogi cymeradwyo, nid yw’n aros am y penderfyniad cymeradwyo neu wrthod, ac ni chaiff ail ddanfoniad ei anfon pan wneir y penderfyniad hwnnw. Triniwch lwyth sy’n dod i mewn fel “mae ymateb yn bodoli”, nid fel “mae ymateb wedi’i gymeradwyo”.
Pam nad yw’r llofnod yn ddewisol
Cyfrinach sy’n gollwng yw URL webhook. Mae’n cyrraedd tocyn cymorth, neges Slack, sgrinlun mewn dogfen drosglwyddo, hanes porwr ar liniadur a rennir. Heb lofnod, gall unrhyw un sydd wedi gweld yr URL bostio beth bynnag y mynno ato, a bydd eich systemau’n ei ffeilio fel ymateb dilys i ymgynghoriad. I gyngor sy’n cyfrif gwrthwynebiadau i gais cynllunio, nid problem ddamcaniaethol mo honno.
Felly caiff pob danfoniad ei lofnodi. Mae gan bob webhook ei gyfrinach ei hun a gynhyrchir ar hap, ac a ddangosir yn yr adeiladwr y tu ôl i fotwm “dangos y gyfrinach lofnodi”. Rydym yn cyfrifo HMAC-SHA256 dros union feit corff y cais gan ddefnyddio’r gyfrinach honno; rydych chi’n ei ailgyfrifo gyda’ch copi chi ac yn cymharu. Mae cais wedi’i ffugio’n methu, am nad oes gan y ffugiwr y gyfrinach.
Rhaid i’r URL fod yn https. Caiff hynny ei orfodi gan
gyfyngiad yn y gronfa ddata, nid gan awgrym yn y ffurflen, am nad yw
cyfrinach lofnodi sy’n teithio dros gysylltiad heb ei amgryptio yn
gyfrinach.
Gwirio danfoniad yn Node.js
Mae dau fanylyn yn gwneud y rhan fwyaf o’r difrod yn ymarferol. Defnyddiwch gorff crai’r cais, nid gwrthrych sydd wedi’i ddosrannu a’i ailgyfresoli — mae gwahaniaethau gofod gwyn yn newid yr hash. A chymharwch mewn amser cyson, fel na all ymosodwr ddysgu’r llofnod cywir un beit ar y tro o amseriadau’r ymateb.
import { createHmac, timingSafeEqual } from 'node:crypto';
const SECRET = process.env.NOISSIME_WEBHOOK_SECRET;
// rawBody must be the exact bytes received, before any JSON parsing.
// Re-serialising a parsed object changes the whitespace and the check fails.
function isFromNoissime(rawBody, header) {
if (typeof header !== 'string') return false;
const expected =
'sha256=' + createHmac('sha256', SECRET).update(rawBody).digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(header);
// timingSafeEqual throws on a length mismatch, so compare lengths first.
return a.length === b.length && timingSafeEqual(a, b);
}Galwch hynny cyn i chi ddosrannu dim. Os yw’n dychwelyd gau, atebwch 401 a thaflwch y cais. Os yw’n dychwelyd gwir, mae gennych ymateb na all fod wedi dod o unman ond eich arolwg chi.
Y log danfon
Mae webhook sydd wedi peidio â gweithio’n dawel yn edrych yn union fel un na chafodd ei alw erioed: nid oes dim yn digwydd, ac nid oes dim yn dweud wrthych. Felly caiff pob ymgais ei hysgrifennu i log danfon, a dangosir y statws HTTP diwethaf wrth ymyl y webhook yn yr adeiladwr — gwyrdd am 2xx, coch am unrhyw beth arall.
Mae’r danfon yn anghydamserol, felly caiff y statws ei gysoni wedi’r digwyddiad yn hytrach na’i ddyfalu ar foment yr anfon. Yr hyn a welwch yw’r statws a ddychwelodd eich gweinydd mewn gwirionedd. Cewch atal webhook dros dro a’i ailgychwyn heb ei ddileu, sef y peth arferol rydych ei eisiau tra bo’r system sy’n derbyn yn cael ei hailosod.
Un terfyn bwriadol: nid oes ailgeisio gydag oedi cynyddol. Caiff danfoniad ei geisio unwaith, caiff y canlyniad ei gofnodi, a dyna ddiwedd arni. Mae adeiladu ciw ailgeisio sy’n parchu trefn ac idempotedd yn waith go iawn, a byddai honni bod gennym un nad ydym wedi’i adeiladu yn waeth na dweud hyn. Yn y cyfamser nid yw’r ymateb byth ar goll — mae yn y gronfa ddata, yn weladwy ar y dudalen dadansoddeg ac adrodd, ac mae modd ei allforio fel CSV.
Ni all webhook sy’n methu dorri’r casglu chwaith. Os yw’r danfon yn taflu gwall, caiff y gwall ei gofnodi ac mae’r ymateb yn dal i gael ei gofnodi. Ateb yr ymatebydd yw’r peth sy’n cyfrif; ymdrech orau yw’r danfon.
Hysbysiadau e-bost, heb yr atebion
Ychwanegwch y cyfeiriadau a ddylai glywed am ymatebion newydd, ac anfonir e-bost atynt pan fydd un yn cyrraedd. Mae’r neges yn HTML wedi’i brandio gyda dewis amgen mewn testun plaen, am fod cleientiaid testun-yn-unig a hidlwyr sbam ill dau yn darllen y rhan blaen. Mae’n enwi’r arolwg, yn rhoi cyfanswm yr ymatebion hyd yma, ac yn cysylltu â’r canlyniadau.
Yr hyn nad yw’n ei gynnwys yw’r atebion. Penderfyniad yw hynny, nid diffyg. Caiff e-bost hysbysu ei anfon ymlaen at gydweithiwr, ei awto-ffeilio i flwch post a rennir, ei gydamseru i ffôn a’i gadw mewn copi wrth gefn am flynyddoedd. Mae rhoi atebion testun rhydd o ymgynghoriad i mewn i’r gadwyn honno’n gwasgaru data personol ar draws systemau nad oes neb wedi’u hasesu, ac yn dadwneud yn dawel y rheolaethau mynediad a ddisgrifir ar y dudalen ddiogelwch. Mae data ymatebwyr yn aros yn y gronfa ddata, ac mae’r e-bost yn dweud wrthych am fynd i edrych.
Fel webhooks, caiff hysbysiadau eu tanio gan sbardun cronfa ddata, felly maent yn dilyn yr ymateb yn hytrach na llwybr cyflwyno penodol. Os nad oes cyfeiriadau wedi’u ffurfweddu, ni chaiff dim ei anfon ac ni cheisir dim.
Beth nad yw hyn yn ei wneud
- Dim ap Zapier, a dim cysylltydd Google Sheets.
- Dim ailgeisio gydag oedi cynyddol — un ymgais fesul ymateb, ac yna’r log.
- Dim digwyddiadau allanol heblaw
response.created. Nid yw cymeradwyo, golygu na dileu yn tanio webhooks. - Dim API i mewn ar gyfer creu arolygon na darllen ymatebion yn rhaglennol.
- Dim rhestr ganiatáu IP ar gyfer danfoniadau. Y llofnod yw’r dilysu.
Cwestiynau cyffredin
Sut ydw i’n gwirio’r pennyn X-NumoForms-Signature?
Cyfrifwch HMAC-SHA256 o gorff crai’r cais gan ddefnyddio cyfrinach lofnodi’r webhook hwnnw, amgodiwch ef mewn hecs, rhowch “sha256=” o’i flaen, a chymharwch ef â’r pennyn gan ddefnyddio cymhariaeth amser cyson. Gwiriwch cyn dosrannu’r JSON, a gwrthodwch unrhyw beth nad yw’n cyfateb, gyda 401.
Beth sy’n digwydd os yw fy mhwynt terfyn i lawr pan fydd ymateb yn cyrraedd?
Caiff y danfoniad ei geisio unwaith, a chaiff y canlyniad ei gofnodi yn y log danfon gyda’r statws HTTP. Nid oes ailgeisio awtomatig gydag oedi cynyddol. Nid yw’r ymateb ei hun byth mewn perygl: ni all methiant webhook atal ymateb rhag cael ei gadw, a chewch bob amser adfer y data o’r dudalen canlyniadau neu drwy allforio CSV.
A yw webhook yn tanio ar gyfer ymateb a gyflwynwyd o ffurflen wedi’i mewnosod?
Ydy. Caiff y danfon ei danio gan sbardun cronfa ddata ar y tabl ymatebion yn hytrach na chan dudalen benodol yn y rhaglen, felly mae’n digwydd o ble bynnag y daw ymateb — dolen wedi’i chynnal, ffurflen wedi’i mewnosod, neu ymateb rhannol a ailddechreuwyd ac sydd newydd ei gwblhau.
A gaf i anfon webhook at URL http://?
Na chewch. Mae cyfyngiad gwirio yn y gronfa ddata yn mynnu bod yr URL yn dechrau gyda https://, ac mae’r adeiladwr yn gwrthod unrhyw beth arall. Nid yw cyfrinach lofnodi a anfonir dros gysylltiad heb ei amgryptio yn gyfrinach.
A yw e-byst hysbysu yn cynnwys atebion yr ymatebydd?
Nac ydynt, yn fwriadol. Mae’r e-bost yn dweud bod ymateb wedi cyrraedd, yn enwi’r arolwg, yn rhoi’r cyfanswm hyd yma ac yn cysylltu â’r canlyniadau. Caiff hysbysiadau eu hanfon ymlaen, ac maent yn eistedd mewn copïau wrth gefn o flychau post, felly mae data ymatebwyr yn aros yn y gronfa ddata lle mae’r rheolaethau mynediad.
A oes ap Zapier neu gysylltydd Google Sheets?
Nac oes. Webhooks yw’r unig integreiddiad allanol heddiw. Nid oes ap Zapier na chysylltydd Google Sheets, ac nid oes dyddiad cyhoeddedig ar gyfer y naill na’r llall.
Cysylltwch arolwg â’ch systemau eich hun.
Cyfeiriwch webhook at bwynt terfyn https ac mae pob ymateb yn cyrraedd yno wedi’i lofnodi, fel y gall eich derbynnydd brofi mai oddi wrthym ni y daeth ac nid oddi wrth bwy bynnag a ddaeth o hyd i’r URL. Ychwanegwch y cyfeiriadau i’w e-bostio pan fydd ymateb yn glanio, ac mae’r atebion yn aros yn y gronfa ddata lle mae’r rheolaethau mynediad.
- Llofnod HMAC-SHA256 ar bob danfoniad
- Cofnod danfon yn dangos y statws HTTP diwethaf
- Yn tanio o sbardun cronfa ddata, beth bynnag yw’r llwybr i mewn
