---
title: "Ověření podpisu webhooku: 7 kontrol před zpracováním"
description: "Sedm kontrol pro bezpečný příjem webhooků, stavovou idempotenci a obnovu událostí bez opakování dokončené obchodní akce."
url: "https://blog.lucidmark.cz/blog/overeni-podpisu-webhooku"
language: "cs"
author: "Roman Mrózek"
author_url: "https://blog.lucidmark.cz/autor/romanmrozek"
publisher: "LucidMark s.r.o."
date_published: "2026-09-22T17:02:41.872Z"
date_modified: "2026-09-22T17:02:41.778Z"
category: "Vývoj"
reading_time_minutes: 5
sources:
  - title: "Standard Webhooks specification"
    url: "https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md"
  - title: "GitHub: Validating webhook deliveries"
    url: "https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries"
  - title: "Slack: Verifying requests from Slack"
    url: "https://docs.slack.dev/authentication/verifying-requests-from-slack/"
  - title: "GitHub: Handling webhook deliveries"
    url: "https://docs.github.com/en/webhooks/using-webhooks/handling-webhook-deliveries"
---

# Ověření podpisu webhooku: 7 kontrol před zpracováním

> Sedm kontrol pro bezpečný příjem webhooků, stavovou idempotenci a obnovu událostí bez opakování dokončené obchodní akce.

Autor: Roman Mrózek | Publikováno: 22. 9. 2026 | Kategorie: [Vývoj](https://blog.lucidmark.cz/kategorie/vyvoj)  
Původní článek: https://blog.lucidmark.cz/blog/overeni-podpisu-webhooku

Ověření podpisu webhooku je krátká technická vrstva, která chrání následné firemní operace. Když webhook oznamuje platbu, rezervaci nebo změnu stavu, příjemce nemá převést přijatý JSON rovnou na akci. Nejdřív potřebuje ověřit původ a neporušenost zprávy, potom omezit její opakované přehrání a nakonec řídit zpracování tak, aby se po dílčí chybě dalo bezpečně pokračovat. Následujících sedm kontrol tvoří praktické zadání pro implementaci i provoz.

## Co ověření podpisu umí a kde končí

Webhook je HTTP callback, kterým služba oznamuje jiné službě událost. Standard Webhooks považuje ověření autenticity za nutnou součást bezpečného příjmu a popisuje HMAC se sdíleným tajemstvím i asymetrické podpisy. [Specifikace vysvětluje oba přístupy](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md).

Při důvěryhodném a nekompromitovaném klíči úspěšné ověření potvrzuje, že podepsaná data vytvořil někdo s odpovídajícím klíčem a že se podepsané bajty nezměnily. Sám však neříká, zda už firma událost úspěšně zpracovala. Návrh proto rozdělte na tři brány: ověření podpisu, ochranu proti replay útoku a stavové řízení obchodní operace. Každou bránu testujte samostatně. [Rozsah ověření podpisu popisuje Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md).

## 1. Zachyťte původní tělo požadavku

Podpis ověřujte nad stejnými bajty, které podepsal odesílatel. Standard Webhooks upozorňuje, že i mezera nebo opětovná serializace JSON může změnit podepisovaný obsah. GitHub ve svých příkladech pracuje s původním tělem a v řešení problémů výslovně radí ověřit, že proxy nebo load balancer před validací nezměnily payload ani hlavičky. [Podrobnosti uvádí Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md) a [dokumentace GitHubu](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries).

Nechte framework zpřístupnit původní tělo ještě před parsováním. Do integračního testu vložte payload s diakritikou, změnu jediného znaku a průchod přes skutečnou proxy. Správná zpráva má projít, změněná musí skončit před obchodní logikou.

## 2. Sestavte podpis přesně podle dodavatele

Nevytvářejte univerzální formát odhadem. GitHub používá obsah payloadu, HMAC-SHA256 a hlavičku X-Hub-Signature-256. Slack naopak skládá podepisovaný základ z verze, časového razítka a původního těla. [Přesný postup popisuje GitHub](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries) a [Slack](https://docs.slack.dev/authentication/verifying-requests-from-slack/).

Pro každou integraci evidujte algoritmus, verzi schématu, jména potřebných hlaviček a způsob načtení tajemství. Pokud dodavatel nabízí oficiální knihovnu pro používaný jazyk, zvažte ji. Vlastní implementaci ověřte testovacím payloadem a očekávaným podpisem z dokumentace dodavatele.

## 3. Porovnejte podpis bezpečnou funkcí

Vypočtený a přijatý podpis neporovnávejte běžným operátorem rovnosti. GitHub doporučuje funkci pro porovnání v konstantním čase, například secure\_compare nebo timingSafeEqual, aby omezil riziko časových útoků. [Stejné doporučení obsahuje oficiální návod GitHubu](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries).

Neplatný, chybějící nebo chybně zakódovaný podpis odmítněte jednotnou cestou před změnou dat. Do logu uložte název integrace, identifikátor doručení a důvod odmítnutí. Nevypisujte celé tajemství ani zbytečně celý payload.

## 4. Oddělte tajemství od kódu a naplánujte rotaci

Webhookové tajemství uložte do chráněné konfigurace, ke které má přístup jen přijímací komponenta. GitHub výslovně říká, že token nemá být natvrdo v aplikaci ani odeslán do repozitáře. [Požadavek je v dokumentaci GitHubu](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries).

Rotaci navrhněte podle možností konkrétního poskytovatele. Standard Webhooks podporuje přechod zasláním podpisů vytvořených současným i starým klíčem po omezenou dobu; příjemce zkouší podpisy, dokud jeden neodpovídá. [Mechanismus popisuje specifikace](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md). Nekopírujte jej k dodavateli, který dokumentuje jiný postup.

## 5. Zkontrolujte stáří podepsané zprávy

Je-li časové razítko součástí podepisovaných dat, ověřte také jeho přijatelné stáří. Standard Webhooks popisuje čas pokusu jako ochranu proti replay útokům. Slack zahrnuje čas do podpisu a ve svém příkladu odmítá požadavek, jehož čas se od místního liší o více než pět minut. [Role času je ve Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md) a [pětiminutový příklad v dokumentaci Slacku](https://docs.slack.dev/authentication/verifying-requests-from-slack/).

Pět minut není univerzální hodnota. Použijte toleranci dodavatele a sledujte synchronizaci času serveru. Chybějící, nečitelná nebo příliš stará hodnota má skončit odmítnutím před obchodní akcí.

## 6. Řiďte idempotenci stavovým automatem

Standard Webhooks rozlišuje čas konkrétního pokusu a stabilní identifikátor události; identifikátor doporučuje použít jako idempotency key. [Specifikace vysvětluje role obou hodnot](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md). Pouhé pravidlo „ID už existuje, nic nedělej“ ale nestačí, protože první pokus mohl skončit uprostřed práce.

Pro každé ID veďte alespoň stavy **přijatý**, **zařazený**, **zpracovávaný**, **dokončený** a **neúspěšný**. Přechody definujte předem:

- **přijatý**: ověřená událost je trvale uložená;
- **zařazený**: existuje úloha připravená pro zpracování;
- **zpracovávaný**: pracovní proces drží časově omezený zámek;
- **dokončený**: nevratná obchodní akce proběhla a výsledek je zaznamenán;
- **neúspěšný**: pokus skončil chybou a obsahuje důvod i počet pokusů.

Duplicitní doručení dokončené události nesmí zopakovat nevratnou akci. Událost ve stavu přijatý nebo neúspěšný však musí jít bezpečně znovu zařadit. Uvíznuté zpracování obnovte až po vypršení zámku. Pokud databáze a fronta neumějí společnou transakci, zvažte transakční outbox: spolu s událostí uložte záznam k odeslání a samostatný proces jej předá do fronty. Podrobnější návrh souběhů najdete v článku [Idempotentní n8n webhook: jak zabránit duplicitám](https://blog.lucidmark.cz/blog/idempotentni-n8n-webhook-jak-zabranit-duplicitam).

## 7. Potvrďte příjem v limitu poskytovatele

Nejprve zjistěte, co poskytovatel považuje za úspěšné doručení. GitHub požaduje odpověď 2XX do deseti sekund; po překročení limitu spojení ukončí a doručení označí jako neúspěšné. [Limit uvádí dokumentace GitHubu](https://docs.github.com/en/webhooks/using-webhooks/handling-webhook-deliveries).

Před potvrzením proveďte jen kontroly a trvalé uložení, které potřebujete pro bezpečné převzetí. Volání CRM, tvorbu dokumentu nebo rozesílání e-mailů přesuňte za potvrzení tehdy, pokud by mohly ohrozit limit poskytovatele nebo spolehlivost příjmu. [LucidMark](https://lucidmark.cz) může pomoci navrhnout takové rozhraní jako konkrétní workflow s lidským potvrzením změn dat a auditním logem důležitých akcí.

## Modelový průchod události

**Modelový příklad:** rezervační systém přijme oznámení o platbě. Endpoint zachytí původní tělo, ověří čas a podpis, potom v jedné databázové transakci založí událost jako přijatou a záznam outboxu. Odesílač outboxu ji předá do fronty a stav změní na zařazený. Pracovní proces získá zámek, provede změnu a uloží stav dokončený.

Když pracovní proces selže, stav přejde na neúspěšný a řízený pokus může pokračovat. Když stejné ID dorazí po dokončení, endpoint potvrdí příjem bez nové obchodní akce. Jde o model návrhu, nikoli o popis konkrétního projektu.

## Checklist před spuštěním

- Zachytává endpoint původní tělo před parsováním?
- Odpovídá algoritmus, formát a hlavička dokumentaci dodavatele?
- Odmítne systém neplatný podpis před změnou dat?
- Používá porovnání v konstantním čase?
- Jsou tajemství mimo kód a existuje ověřený postup rotace?
- Kontroluje systém podepsané časové razítko podle pravidel dodavatele?
- Rozlišuje všech pět stavů a umí obnovit přijatou, neúspěšnou nebo uvíznutou událost?
- Brání dokončený stav opakování nevratné akce?
- Vrací endpoint potvrzení v limitu a lze v monitoringu rozlišit chybu podpisu, stáří, fronty a zpracování?

Dobré ověření podpisu webhooku není jen výpočet hashe. Je to měřitelný přijímací proces, který spojuje kontrolu vstupu s obnovitelným zpracováním. Pokud některý bod nemá jednoznačného vlastníka nebo test, nepouštějte integraci do produkce.

## Zdroje a další čtení

1. [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md)
2. [GitHub: Validating webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)
3. [Slack: Verifying requests from Slack](https://docs.slack.dev/authentication/verifying-requests-from-slack/)
4. [GitHub: Handling webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/handling-webhook-deliveries)
