Przejdź do głównej zawartości

Notyfikacje (webhooki)

Notyfikacje to mechanizm, którym Paymentic informuje Twój system o zdarzeniach zachodzących w cyklu życia transakcji — zmianie statusu płatności, zwrotu czy dodatkowych zdarzeniach specyficznych dla BLIK. Są wysyłane jako zapytania HTTP POST na endpoint, który zdefiniujesz w panelu.

Model webhooków ma jedną wyraźną zaletę: Twój system nie musi odpytywać API, żeby dowiedzieć się o zmianie — to Paymentic aktywnie powiadamia o zdarzeniu, zwykle w ciągu kilku sekund od jego zajścia.

Jak to działa w skrócie​

  1. Konfigurujesz URL webhooka w panelu (Integracja → Notyfikacje). Endpoint musi być publiczny i działać po HTTPS.
  2. Zdarzenie w Paymentic (np. transakcja zmienia status na PAID) wyzwala wysyłkę notyfikacji.
  3. Twój endpoint odbiera POST z ciałem JSON i kilkoma nagłówkami X-Paymentic-*.
  4. Weryfikujesz sygnaturę, żeby potwierdzić autentyczność zdarzenia.
  5. Zwracasz HTTP 200 OK (lub 202) — w przeciwnym razie Paymentic ponowi wysyłkę.

Dostępne zdarzenia​

ZdarzenieKiedy jest wysyłaneSzczegóły
PAYMENT.TRANSACTION_STATUS_CHANGEDKażda zmiana statusu transakcji płatniczejSzczegóły
PAYMENT.REFUND_STATUS_CHANGEDKażda zmiana statusu zwrotuSzczegóły
PAYMENT.TRANSACTION_BLIK_STATUS_CHANGEDZmiany statusu po stronie BLIK przy transakcjach BLIK L0Szczegóły
PAYMENT.BLIK_ALIAS_STATUS_CHANGEDZmiany statusu aliasu BLIK (One Click)Szczegóły

Zanim zaczniesz integrację​

Zanim napiszesz obsługę webhooków, warto poznać trzy rzeczy:

  • Struktura notyfikacji — jak wygląda przychodzący request: nagłówki, body, wersjonowanie.
  • Sygnatura — jak zweryfikować, że webhook faktycznie pochodzi od Paymentic.
  • Ponawianie notyfikacji — co się dzieje, gdy Twój endpoint nie odpowie, oraz dlaczego obsługa musi być idempotentna.

Dobre praktyki w skrócie​

  • Zwracaj 200 OK szybko. Ciężkie operacje (wysyłka maila, synchronizacja stanu magazynowego) wykonuj asynchronicznie, po odpowiedzi.
  • Weryfikuj sygnaturę zawsze. Bez tego webhook to tylko nieuwierzytelniony POST z internetu.
  • Obsługa idempotentna. Ten sam X-Paymentic-Notification-Id nie może zmienić stanu zamówienia więcej niż raz.
  • Loguj wszystko. Przy debugowaniu webhooków surowy log zapytania jest na wagę złota.
  • Monitoruj liczbę retry. Nagły wzrost retry na Twoim endpoincie zwykle oznacza awarię, zanim zauważą ją użytkownicy.