Webhookok: aláírás ellenőrzése és újrapróbálás

Minden kézbesítés egy POST kérés JSON-törzzsel: id (eseményazonosító), event, api_version, created_at, workspace_id és data. Az aláírás bizonyítja, hogy a kérés tőlünk jön, és útközben senki nem módosította.

Fejlécek

• Sayweek-Signature: t=<unix másodperc>,v1=<hex> – az aláírás.
• Sayweek-Event-Id – ugyanaz minden újrapróbálásnál és újraküldésnél: ezzel szűrd ki a duplikátumot.
• X-Sayweek-Event – az esemény neve, pl. post.published.
• X-Sayweek-Delivery – a kézbesítés azonosítója (a Kézbesítési napló sorai).
• X-Sayweek-Signature: sha256=<hex> – a régi formátum a korábbi integrációknak; új kódban a Sayweek-Signature fejlécet használd.

Az aláírás ellenőrzése

1. 1Olvasd be a kérés nyers törzsét, pontosan úgy, ahogy megérkezett (ne parszold és ne formázd újra).
2. 2Bontsd szét a Sayweek-Signature fejlécet: a t az időbélyeg, a v1 az aláírás (titokcsere idején több v1 is lehet – bármelyik egyezése elég).
3. 3Számold ki a HMAC-SHA256 értéket az aláírási titokkal a t.törzs szövegre (az időbélyeg, egy pont, majd a nyers törzs), hexadecimálisan.
4. 4Hasonlítsd össze állandó idejű összehasonlítással, és utasítsd el a kérést, ha nem egyezik, vagy ha a t 5 percnél régebbi (így egy elkapott kérést sem lehet később visszajátszani).

Node.js-ben: createHmac("sha256", secret).update(t + "." + rawBody).digest("hex"), majd timingSafeEqual a fejlécben kapott v1 értékkel.

Pythonban: hmac.new(secret.encode(), f"{t}.{raw_body}".encode(), hashlib.sha256).hexdigest(), majd hmac.compare_digest a v1 értékkel.

Újrapróbálás

• Sikeresnek a 2xx válasz számít, 8 másodpercen belül – válaszolj gyorsan, és a hosszabb munkát végezd utána.
• Újrapróbáljuk a hálózati hibát, az időtúllépést, a 408, 409, 425, 429 és minden 5xx választ; a többi 4xx végleges.
• A szünetek: kb. 1 perc, 4 perc, 16 perc, 1 óra, 4 óra, majd 12 óra (kis véletlen eltolással) – összesen legfeljebb 8 próbálkozás, nagyjából másfél nap alatt.
• Ha egy Zapier-, Make- vagy API-s feliratkozás 410 Gone választ ad, a feliratkozást töröljük.

Automatikus kikapcsolás

Ha egy végpontnál legalább 10 próbálkozás egymás után sikertelen, és ez több mint egy napja tart, a webhookot kikapcsoljuk, a tulajdonosok pedig push-értesítést és e-mailt kapnak. Egy rövid leállás tehát sosem kapcsolja ki. Visszakapcsolás: Beállítások → Összes integráció → Webhooks · n8n, a webhook sorában Bekapcsolás – ez nullázza a hibasorozatot. A tesztküldés sosem számít bele.