Stripe Webhook (automaticky konfigurován)
Když zapnete Stripe v Systém › Základní nastavení › Platby › Stripe, váš obchod automaticky nastaví spojení, které umožní Stripu nás upozorňovat na platební události — úspěšné platby, vrácení peněz, spory a neúspěšné pokusy. Nemusíte se přihlašovat do Stripe Dashboardu ani kopírovat žádný „webhook signing secret" — vše uděláme za vás.
TIP
Po nastavení uvidíte na stránce nastavení Stripe zelený rámeček „✓ Webhook byl nakonfigurován automaticky". Pokud místo toho vidíte modrý „Webhook bude automaticky nakonfigurován po uložení Stripe klíčů", stačí uložit klíče a obnovit stránku.
Co je webhook?
Když zákazník dokončí platbu, Stripe potřebuje obchodu sdělit „tato platba proběhla úspěšně". Tato zpráva se nazývá webhook. Bez funkčního webhooku se vrácení peněz, spory a neúspěšné pokusy o platbu nedostanou do seznamu objednávek.
Ruční nastavení webhooku dříve vyžadovalo: přihlášení do Stripe Dashboardu, navigaci do Developers → Webhooks, přidání nového endpointu, výběr seznamu událostí, zkopírování podpisového klíče a vložení zpět do naší administrace. Toto vše jsme nahradili jedním kliknutím na Uložit nastavení.
Jak to funguje
- Vložíte svůj Stripe Publishable Key a Stripe Secret Key do Systém › Základní nastavení › Platby › Stripe. (Najdete je ve Stripe Dashboardu pod Developers → API keys.)
- Kliknete na Uložit nastavení.
- My pomocí vašeho secret key programově zaregistrujeme webhook endpoint ve Stripu, který směřuje na doménu vašeho obchodu (např.
https://vasobchod.cz/api/webhooks/stripe). - Stripe vrátí podpisový klíč. Uložíme ho a používáme k ověření, že příchozí webhook volání skutečně přišla od Stripu.
Vše proběhne během několika sekund. Nikdy nemusíte vidět konfigurační obrazovku webhooku ve Stripe Dashboardu.
Časté situace
„Právě jsem změnil doménu z mojeobchod.merzio.tech na mojeobchod.cz"
Stávající webhook stále funguje — merzio subdoména zůstává aktivní a nadále směřuje na váš obchod, takže notifikace ze Stripu se k nám stále dostávají. Ale URL webhooku směřuje na vaši starou doménu, což je nepořádek.
Pro vyčištění:
- Ujistěte se, že vaše nová doména je plně aktivní (DNS přeloženo, SSL certifikát vydán).
- Přejděte do Systém › Základní nastavení › Platby › Stripe.
- Klikněte na Překonfigurovat vedle indikátoru stavu webhooku.
- Potvrďte dialog. Smažeme starý webhook ve Stripu a vytvoříme nový na vaší nové doméně.
Můžete také prostě znovu uložit nastavení Stripu — ale Překonfigurovat je nejčistší cesta, protože odstraní starý endpoint, místo aby ho nechal viset.
„Vidím varování, že webhook nebylo možné nakonfigurovat"
Nejčastější příčiny:
- „Neplatný Stripe secret key" — secret key, který jste vložili, je špatný, vypršel, nebo patří k jinému Stripe účtu. Získejte nový secret key ze Stripe Dashboard → Developers → API keys a vložte ho znovu.
- „Tento obchod nemá nastavenou primární doménu" — pro tento obchod jste ještě neaktivovali doménu. Nejprve přidejte a ověřte doménu v Domény, poté znovu uložte nastavení Stripu.
- „Webhook endpoint již existuje ve Stripe" — dříve jste si vytvořili webhook endpoint ručně ve Stripe Dashboardu. Buď klikněte na Překonfigurovat pro nahrazení (doporučeno), nebo klikněte na Pokročilé: vložit tajný klíč ručně dole a vložte existující podpisový klíč ze Stripe Dashboardu.
WARNING
I když vidíte varování, ostatní nastavení Stripu jsou stále uložena. Platby kartou budou nadále fungovat — ale funkce, které závisí na webhoocích (synchronizace stavu vrácení peněz, notifikace o neúspěšných platbách), se nebudou aktualizovat, dokud nebude webhook nakonfigurován.
„Chci použít webhook, který jsem už ručně vytvořil ve Stripe"
Klikněte na Pokročilé: vložit tajný klíč ručně ve spodní části sekce webhook. Vložte existující podpisový klíč ze Stripe Dashboardu. Uložte. Použijeme tento klíč místo vytváření nového.
„Chci rotovat podpisový klíč"
Klikněte na Překonfigurovat. Smažeme stávající endpoint ve Stripu a vytvoříme zcela nový s novým podpisovým klíčem. Starý klíč přestane fungovat okamžitě.
Které události sledujeme
Přihlašujeme se k odběru událostí, které váš obchod potřebuje:
payment_intent.succeeded— platba úspěšně dokončenapayment_intent.payment_failed— karta odmítnuta / 3DS selhalopayment_intent.canceled— zákazník zrušil platbu uprostřed procesucharge.refunded,charge.refund.updated,refund.created,refund.updated,refund.failed— životní cyklus vrácení peněz
Nemusíte ručně přidávat ani odebírat události. Pokud se v budoucnu stanou relevantními nové události, přidají se během aktualizace platformy.
Jak ověřit, že funguje
Nejspolehlivější kontrola:
- Ve Stripe Dashboard → Developers → Webhooks klikněte na endpoint směřující na doménu vašeho obchodu.
- Klikněte na Send test webhook.
- Vyberte
payment_intent.succeededa klikněte na Send. - Odpověď by měla být 200 OK. Pokud místo toho vidíte „Invalid signature", klikněte na Překonfigurovat v administraci vašeho obchodu pro rotaci klíče.