Czym są webhooks w Stripe
Webhook to żądanie HTTP POST, które Stripe wysyła na podany przez Ciebie URL za każdym razem, gdy w Twoim koncie wydarzy się coś istotnego: płatność, zwrot, nowa subskrypcja, spór.
Webhook = „hej, właśnie coś się stało w Twoim koncie Stripe, oto dane tego zdarzenia w formacie JSON".
Zamiast co minutę odpytywać API Stripe „czy już ktoś zapłacił?" (polling), Stripe sam Cię powiadomi w momencie, gdy płatność się zakończy. To efektywniejsze, szybsze i bardziej niezawodne.
Jak wygląda webhook od Stripe
Każdy webhook zawiera obiekt Event z typem zdarzenia i pełnymi danymi. Przykładowa struktura:
{
"id": "evt_1PqR2sA0B3cD4eF5gH6iJ7k",
"type": "checkout.session.completed",
"data": {
"object": {
"id": "cs_live_...",
"amount_total": 9900,
"currency": "pln",
"customer_details": {
"name": "Jan Kowalski",
"email": "jan@firma.pl",
"tax_ids": [{ "type": "pl_vat", "value": "PL1234567890" }]
},
"metadata": { ... }
}
}
}Twój endpoint odbiera ten JSON, parsuje dane i wykonuje akcję, na przykład wystawia fakturę w programie księgowym.
Nie musisz budować tego sam. Stripto odbiera webhooks ze Stripe, wyciąga dane i tworzy fakturę w Fakturowni lub inFakt automatycznie. Konfiguracja zajmuje minutę.
Które zdarzenia Stripe nasłuchiwać do fakturowania
Stripe obsługuje ponad 200 typów zdarzeń. Do automatycznego fakturowania potrzebujesz dwóch:
checkout.session.completedOdpala się po udanej płatności jednorazowej przez Stripe Checkout. Zawiera pełne dane sesji: kwotę, walutę, dane kupującego (imię, e-mail, adres, NIP), opis produktu z line_items. To najczęściej używane zdarzenie do fakturowania.
Kiedy używać: płatności jednorazowe, Payment Links, Stripe Checkout w Twoim sklepie.
invoice.paidOdpala się, gdy Stripe pobierze płatność za subskrypcję (fakturę Stripe). Zawiera dane z obiektu Invoice: kwotę, walutę, dane klienta, pozycje subskrypcji. Odpala się cyklicznie, co miesiąc, kwartał lub rok, zależnie od interwału subskrypcji.
Kiedy używać: subskrypcje, płatności cykliczne, SaaS.
Stripto nasłuchuje obu zdarzeń automatycznie. Nie musisz wybierać, konfigurować ani pisać kodu. Podłączasz Stripe i od razu działa zarówno dla płatności jednorazowych, jak i subskrypcji.
DIY, czyli własna integracja webhook → faktura
Jeśli chcesz samodzielnie zbudować integrację Stripe webhook → faktura w Fakturowni, inFakt lub wFirma, oto co musisz zaimplementować:
- 1
Endpoint HTTP na Twoim serwerze
Serwer (Node.js, Python, PHP, Go) z endpointem POST, który przyjmuje webhooks od Stripe. Musi być publicznie dostępny przez HTTPS.
- 2
Weryfikacja podpisu Stripe-Signature
Każdy webhook od Stripe zawiera nagłówek
Stripe-Signaturez podpisem HMAC-SHA256. Musisz go weryfikować, żeby upewnić się, że żądanie naprawdę pochodzi od Stripe. Bez tego ktoś może wysłać fałszywy webhook na Twój endpoint. - 3
Idempotencja, czyli ochrona przed duplikatami
Stripe może wysłać ten sam webhook wielokrotnie (np. przy timeout). Musisz przechowywać ID zdarzeń i sprawdzać, czy faktura dla danego zdarzenia nie została już wystawiona. Bez tego dostaniesz podwójne faktury.
- 4
Mapowanie danych Stripe → program księgowy
Zamiana danych ze Stripe (amount w groszach, currency, customer_details, tax_ids, line_items) na format API Fakturowni, inFakt lub wFirma (buyer_name, buyer_tax_no, positions, price_net, tax). To najtrudniejsza część, bo trzeba obsłużyć różne waluty, stawki VAT, brakujące pola i edge cases.
- 5
Wywołanie API programu księgowego
Wysłanie żądania POST do API Fakturowni (/invoices.json) lub inFakt (/invoices) z danymi faktury. Obsługa kodów błędów, walidacji i retry przy tymczasowych problemach.
- 6
Obsługa błędów i monitoring
Logowanie błędów, alerty przy nieudanych fakturach, retry z exponential backoff dla tymczasowych awarii API, dashboard do śledzenia statusów. Bez tego nie wiesz, czy faktura się wystawiła, dopóki klient nie zapyta.
Ile pracy wymaga własna integracja
Sam endpoint webhook to kilkadziesiąt linii kodu. Ale produkcyjna integracja wymaga znacznie więcej:
- Idempotencja: Stripe może wysłać ten sam webhook wielokrotnie. Bez sprawdzania duplikatów dostaniesz podwójne faktury.
- Mapowanie danych: kwoty w groszach, NIP z prefiksem kraju, adresy w różnych formatach. Musisz to zmapować na format API Fakturowni, inFakt lub wFirma.
- Obsługa walut: przeliczanie kwot, formatowanie zgodne z oczekiwaniami programu księgowego.
- Dwie osobne integracje: Fakturownia, inFakt i wFirma mają zupełnie inne API.
- Obsługa błędów i retry: co gdy API Fakturowni nie odpowiada? Ponowne próby, alerty, kolejka nieudanych faktur.
- Utrzymanie: aktualizacje API, monitoring, poprawki błędów.
W sumie to 40–80 godzin pracy programisty, czyli 8 000–16 000 zł przy stawce 200 zł/h. Plus koszty serwera i utrzymania.
Stripto robi dokładnie to samo od 19 zł/mies. Bez pisania kodu, bez serwera, bez utrzymania. Podłączasz Stripe i Fakturownię/inFakt, a faktury wystawiają się same.
DIY vs Stripto: porównanie wysiłku
Samodzielna budowa integracji daje pełną kontrolę, ale kosztuje czas i wymaga utrzymania. Stripto robi to samo bez pisania kodu. Porównanie:
| Aspekt | DIY (własny kod) | Stripto |
|---|---|---|
| Czas wdrożenia | 40–80 godzin (1–2 tygodnie) | 1 minuta |
| Koszt początkowy | 8 000–16 000 zł (praca developera) | 0 zł (5 faktur za darmo) |
| Koszt miesięczny | Serwer + utrzymanie + monitoring | od 19 zł/mies. lub od 190 zł/rok |
| Konfiguracja webhooków | Ręczna (panel Stripe + kod) | Automatyczna |
| Weryfikacja podpisów | Musisz zaimplementować | Wbudowana |
| Idempotencja | Musisz zaimplementować | Wbudowana |
| Obsługa Fakturowni + inFakt | Dwie osobne integracje | Oba wbudowane |
| Obsługa błędów i retry | Musisz zaimplementować | Automatyczna |
| Panel ze statusami faktur | Musisz zbudować | Wbudowany |
| Aktualizacje API | Twoja odpowiedzialność | Automatyczne |
| Pełna kontrola nad logiką | Tak | Ograniczona (konfiguracja w UI) |
Kiedy warto budować samemu? Gdy masz niestandardową logikę fakturowania (np. selektywne fakturowanie, własne reguły VAT, integracja z ERP) i dysponujesz zespołem programistycznym, który będzie to utrzymywać. Dla standardowego przypadku, gdzie każda płatność oznacza fakturę, Stripto jest tańsze i szybsze.
Jak Stripto obsługuje webhooks Stripe
Stripto automatyzuje cały łańcuch od webhooka do faktury. Nie musisz pisać kodu, konfigurować endpointów ani zarządzać podpisami.
- 1
Podłączasz konto Stripe w panelu Stripto
Podajesz klucz API Stripe. Stripto automatycznie tworzy webhook endpoint w Twoim koncie Stripe, więc nie musisz wchodzić do panelu Stripe.
- 2
Podłączasz Fakturownię, inFakt lub wFirma
Podajesz klucz API programu księgowego. Stripto testuje połączenie i konfiguruje mapowanie danych.
- 3
Klient płaci, a faktura powstaje automatycznie
Stripe wysyła webhook do Stripto. Stripto weryfikuje podpis, sprawdza idempotencję, mapuje dane na format programu księgowego i tworzy fakturę ustrukturyzowaną. Program księgowy wysyła ją do KSeF. Cały proces trwa kilka sekund.
1 min
Czas konfiguracji
0 linii kodu
Nic nie programujesz
od 19 zł/mies.
Plan Mini
Szczegółowy opis automatycznego fakturowania ze Stripe znajdziesz w przewodniku po automatycznych fakturach.
Nie pisz kodu, podłącz Stripto
Automatyczne faktury z webhooków Stripe w minutę. Bez serwera, bez kodu, bez utrzymania.
Najczęściej zadawane pytania
Który webhook Stripe jest najważniejszy do fakturowania?
Najważniejsze jest checkout.session.completed, czyli zdarzenie potwierdzające, że klient zapłacił. Zawiera wszystkie dane potrzebne do wystawienia faktury: kwotę, walutę, dane kupującego, NIP (jeśli podany) i opis produktu. Stripto nasłuchuje właśnie tego zdarzenia.
Czy muszę samodzielnie konfigurować webhook w Stripe?
Jeśli używasz Stripto, to nie. Stripto automatycznie tworzy webhook endpoint w Twoim koncie Stripe podczas konfiguracji. Nie musisz wchodzić do panelu Stripe ani pisać kodu. Jeśli budujesz własną integrację, to tak, musisz ręcznie skonfigurować endpoint, weryfikację podpisów i obsługę zdarzeń.
Jaka jest różnica między checkout.session.completed a invoice.paid?
checkout.session.completed odpala się po jednorazowej płatności przez Stripe Checkout. invoice.paid odpala się, gdy Stripe pobierze płatność za subskrypcję (cyklicznie). Jeśli masz oba typy płatności, musisz nasłuchiwać obu zdarzeń. Stripto obsługuje oba automatycznie.
Co się stanie, jeśli mój serwer nie odpowie na webhook?
Stripe automatycznie ponawia wysyłkę webhooka. Jeśli Twój endpoint nie zwróci kodu 200 w ciągu 20 sekund, Stripe spróbuje ponownie, nawet przez 3 dni, z rosnącymi odstępami (exponential backoff). Po wyczerpaniu prób zdarzenie jest oznaczane jako nieudane. Stripto obsługuje to automatycznie, więc nie musisz martwić się o dostępność serwera.
Czy Stripto obsługuje webhook charge.succeeded?
Stripto nasłuchuje checkout.session.completed i invoice.paid, czyli zdarzeń z najlepszymi danymi do fakturowania. charge.succeeded zawiera mniej informacji (brak danych z Checkout, brak line_items) i nie jest rekomendowany do wystawiania faktur.
Ile kosztuje zbudowanie własnej integracji webhook → faktura?
W kosztach programistycznych: 40–80 godzin pracy developera na MVP (webhook, mapowanie danych, integracja z API Fakturowni/inFakt, obsługa błędów, retry, idempotencja, testy). Przy stawce 200 zł/h to 8 000–16 000 zł. Plus utrzymanie, monitoring i aktualizacje API. Stripto kosztuje od 19 zł/mies. i jest gotowe w minutę.
Czy mogę filtrować, które płatności Stripe generują faktury?
W samodzielnej integracji tak, ale musisz to zaprogramować. W Stripto każda udana płatność ze Stripe generuje fakturę automatycznie. Jeśli potrzebujesz selektywnego fakturowania (np. tylko B2B z NIP-em), własna integracja daje więcej kontroli, ale wymaga znacznie więcej pracy.
Czy Stripe webhook jest bezpieczny?
Tak, pod warunkiem że weryfikujesz podpis. Każdy webhook od Stripe zawiera nagłówek Stripe-Signature z podpisem HMAC. Musisz go sprawdzić używając webhook secret (whsec_...) z panelu Stripe. Bez weryfikacji ktoś może wysłać fałszywy webhook na Twój endpoint i spowodować wystawienie fałszywej faktury. Stripto weryfikuje podpisy automatycznie.
Połącz Stripe z Fakturownią, inFakt lub wFirma
Konfiguracja w minutę. Automatyczne faktury gotowe na KSeF.