Webhooki preprosto razloženo: podpis, ponovitev, varnost

Webhook je klic v drugo smer. Namesto da vaš sistem pri storitvi vsakih nekaj minut sprašuje, ali se je kaj zgodilo, storitev prikliče naslov pri vas, takoj ko se zgodi. To prihrani poizvedbe in hitreje dostavi novice. Za to morate zagotoviti prejemnika in ga zavarovati. Članek razlaga oboje.

Webhook ali poizvedba API

V praksi mnogi združujejo oboje: Webhook sporoči dogodek, API po potrebi prinese podrobnosti ali zapolni vrzeli po izpadu.

Kako poteka dostava

1. Nastopi dogodek, na primer „plačilo prejeto“.
2. Pošiljatelj pošlje POST z JSON na vaš shranjeni naslov (HTTPS).
3. Vaš prejemnik preveri podpis, si zapomni sporočilo in hitro odgovori s kodo iz območja 2xx.
4. Dejansko delo nato opravi vaš sistem.

Korak 3 je pomemben. Stripe v dokumentaciji webhookov priporoča, da se takoj vrne koda 2xx, preden steče zahtevna logika, ki bi lahko sprožila časovno omejitev. Kdor najprej knjiži račun in šele nato odgovori, tvega nepotrebne ponovitve.

Podpis: kako preverite izvor

Vaš naslov je javno dosegljiv. Vsakdo bi lahko nanj pošiljal izmišljena sporočila. Zato resni pošiljatelji vsako sporočilo podpišejo s skupno skrivnostjo. Običajen je HMAC s SHA-256 prek vsebine, pogosto skupaj s časovnim žigom. GitHub postopek opisuje tako: HMAC-SHA256 prek vsebine, prikazan šestnajstiško, z glavo X-Hub-Signature-256. Primerjava naj poteka s funkcijo s stalnim časom delovanja, da napadalci iz odzivnih časov ne morejo ničesar izpeljati.

Pomembne točke za vašega prejemnika:

• Uporabite surovo vsebino. Podpis izračunajte prek prejetih bajtov, ne prek znova serializiranega JSON. Že drug prelom vrstice spremeni podpis.
• Preverite časovni žig. Stripe v podpisu uporablja časovni žig in privzeto toleranco pet minut, da prepreči napade s ponovitvijo. Toleranca 0 preverjanje izklopi.
• Skrivnost obdržite skrito. Ne v kodi, ne v repozitoriju, ampak v okoljski spremenljivki ali trezorju.

Odprtokodne smernice za pošiljatelje in prejemnike zbira pobuda Standard Webhooks. Kako posamezen ponudnik konkretno oblikuje svoj podpis, piše v njegovi dokumentaciji.

Ponovitve in dvojna dostava

Če vaš prejemnik ne odgovori ali odgovori s kodo napake, pošiljatelj poskusi znova. Stripe po lastni dokumentaciji ponavlja z naraščajočimi razmiki do tri dni. Drugi ponudniki imajo druga pravila, nekateri po preveč neuspehih webhook izklopijo. Iz tega sledi:

• Računajte z dvojniki. Isti dogodek lahko prispe večkrat, tudi če vaš prejemnik deluje pravilno. Stripe na to izrecno opozarja.
• Obdelavo naredite idempotentno. To pomeni: Kdor isto sporočilo obdela dvakrat, ne ustvari drugega rezultata. Shranite oznako dogodka in znane preskočite.
• Ne zanašajte se na vrstni red. Dogodki lahko prispejo zamenjani. Ob dvomu preverite trenutno stanje prek API.

Varnost na obeh straneh

Za prejemnike: samo HTTPS, preverite podpis in starost, omejite velikost sporočila, iz vsebine ne izvajajte ukazov. Z vsebino ravnajte kot z vsakim vnosom od zunaj.

Za pošiljatelje, ki kličejo naslove strank: Kdor ponuja webhooke, kliče naslove, ki so jih vpisali drugi. To je klasična pot za Server-Side Request Forgery. Napadalec vpiše notranji naslov. Strežnik ga prikliče iz zaščitenega omrežja. Opis OWASP kot cilje navaja na primer notranje storitve in metapodatkovne naslove ponudnikov oblaka. Smiselni zaščitni ukrepi:

• dovolite samo https://,
• naslov razrešite ob vpisu in pred vsakim priklicem ter zavrnite zasebna, lokalna in rezervirana območja,
• preusmeritvam ne sledite slepo,
• postavite kratke časovne omejitve.

Primer: pošiljanje testnega sporočila s curl

S curl in openssl lahko svojega prejemnika preizkusite brez pravega pošiljatelja. Skript pošlje podpisano sporočilo, kot bi ga s časovnim žigom poslal pošiljatelj:

GEHEIMNIS="test-geheimnis"
ZEIT=$(date +%s)
INHALT='{"id":"evt_1","typ":"besuch.begonnen","firma":"beispiel-firma.example"}'
SIGNATUR="sha256=$(printf '%s.%s' "$ZEIT" "$INHALT" | openssl dgst -sha256 -hmac "$GEHEIMNIS" | sed 's/^.* //')"

curl -X POST http://localhost:3000/webhook \
  -H "Content-Type: application/json" \
  -H "X-Zeit: $ZEIT" \
  -H "X-Signatur: $SIGNATUR" \
  -d "$INHALT"

Primer: majhen prejemnik v Node.js

const http = require('http')
const crypto = require('crypto')
const GEHEIMNIS = process.env.WEBHOOK_GEHEIMNIS || 'test-geheimnis'
const gesehen = new Set() // v resnici: zbirka podatkov

http.createServer((req, res) => {
  if (req.method !== 'POST' || req.url !== '/webhook') { res.writeHead(404); return res.end() }
  const teile = []
  req.on('data', t => teile.push(t))
  req.on('end', () => {
    const roh = Buffer.concat(teile).toString('utf8')
    const zeit = req.headers['x-zeit'] || ''
    const erwartet = 'sha256=' + crypto.createHmac('sha256', GEHEIMNIS).update(zeit + '.' + roh).digest('hex')
    const erhalten = String(req.headers['x-signatur'] || '')
    const a = Buffer.from(erwartet), b = Buffer.from(erhalten)
    const echt = a.length === b.length && crypto.timingSafeEqual(a, b)
    const frisch = Math.abs(Date.now() / 1000 - Number(zeit)) < 300
    if (!echt || !frisch) { res.writeHead(401); return res.end() }
    const ereignis = JSON.parse(roh)
    if (!gesehen.has(ereignis.id)) { gesehen.add(ereignis.id); console.log('neu:', ereignis.typ) }
    res.writeHead(200); res.end('ok')
  })
}).listen(3000)

Prejemnik preveri podpis in starost, preskoči znane oznake in takoj odgovori. Za obratovanje dodatno potrebujete HTTPS, omejitev velikosti in čakalno vrsto za nadaljnjo obdelavo.

Kje so webhooki razširjeni

Plačilne storitve, kodne platforme in orodja za obrazce dogodke sporočajo prek webhookov. Zmore jih tudi prepoznavanje obiskovalcev: Ko sistem sporoči podjetje, ki obišče vašo stran, pristane neposredno v orodju po vaši izbiri. Kako to vodi v prodajni sistem, kaže Prenos obiskov spletne strani v CRM. Alternativo s poizvedbo opisuje Katera podjetja obiskujejo mojo spletno stran?. Kateri podatki pri tem tečejo, pojasnjuje Kako deluje prepoznavanje podjetij?.

Pogosta vprašanja

Kakšna je razlika med webhookom in API? Pri API vaš sistem sprašuje, pri webhooku se pošiljatelj oglasi sam. Oboje je mogoče združiti.

Kaj se zgodi, če moj prejemnik odpove? Večina pošiljateljev dostavo ponavlja v določenem obdobju. Kako dolgo in kako pogosto, piše v dokumentaciji ponudnika. Za vrzeli načrtujte uskladitev prek API.

Ali zadošča preveriti naslov pošiljatelja? Ne. Naslovi pošiljateljev se dajo ponarediti in se spreminjajo. Zanesljiv je samo podpis s skrivnostjo, ki jo poznate samo vi in pošiljatelj.