Przejdź do głównej zawartości

Webhooki

Sellf wysyła zdarzenia do skonfigurowanych endpointów HTTPS. Każda dostawa jest zapisywana przed wysłaniem żądania HTTP. Nieudane próby trafiają do kolejki ponowień.

Pełny zwrot płatności za subskrypcję kończy ją od razu i odbiera dostęp. Kolejny płatny okres wymaga nowego zakupu. Wygrany spór przywraca pierwotne uprawnienie, także gdy gość potwierdził adres email w trakcie sporu.

W Webhooki → Edytuj wybierz Wygeneruj nowy sekret i potwierdź. Możesz też wywołać POST /api/v1/webhooks/{id}/rotate-secret z sesją administratora lub kluczem API z uprawnieniem webhooks:write. Treść żądania nie jest wymagana. Odpowiedź po sukcesie: { "data": { "id": "…", "secret": "whsec_…" } }.

Zmiana i wpis audytu są zatwierdzane atomowo. Nowy sekret jest szyfrowany w bazie i zwracany tylko w tej odpowiedzi; panel pokazuje go do zamknięcia okna edycji. Skopiuj go teraz do magazynu sekretów odbiornika. Po rotacji odpowiedzi API listy, szczegółów i aktualizacji zwracają puste pole secret; wartości nie można ponownie odczytać. Jeśli ją utracisz, wykonaj kolejną rotację. Istniejące endpointy zachowują dotychczasowy sekret do jawnego wykonania rotacji.

Stary sekret jest unieważniany natychmiast, bez okresu przejściowego. Uzgodnij zmianę z odbiornikiem i natychmiast podmień jego sekret weryfikacyjny. W trakcie zmiany dostawy mogą się nie powieść. Żądania już w drodze mogą nadal mieć poprzedni podpis; dostawy pobierane po zmianie, także ponowienia i wysyłki testowe, używają aktualnego sekretu. Rotacja nie zmienia podpisu już wysłanego żądania HTTP. Po aktualizacji odbiornika wyślij test i w razie potrzeby ponów nieudane dostawy. Identyfikatory i payloady dostaw pozostają bez zmian: nadal deduplikuj po id.

Jeśli odpowiedź zaginie po zatwierdzeniu operacji, stary sekret i tak przestaje działać. Wygeneruj kolejny sekret i zainstaluj wartość z nowej odpowiedzi. Nie ponawiaj żądań rotacji automatycznie: każde udane wywołanie ponownie zmienia sekret.

{
"id": "5cb0a355-840e-4d73-8ab9-34137a763c39",
"event": "purchase.completed",
"timestamp": "2026-10-02T12:34:56.789Z",
"data": {}
}

Nagłówek X-Sellf-Delivery-Id zawiera ten sam UUID co pole id na najwyższym poziomie payloadu. Każdy endpoint otrzymuje własny identyfikator dostawy. Automatyczne oraz ręczne ponowienia używają tego samego identyfikatora i zapisanych danych zdarzenia. Personalizacja payloadu nie może zmienić ani usunąć pola id. To dodatkowe pole koperty: event, timestamp, data oraz format podpisu pozostają bez zmian.

Deduplikuj po tym identyfikatorze (deduplicate on this id). Sellf stosuje semantykę „co najmniej raz”: po timeoutcie lub przerwaniu działania nadawcy ten sam webhook może dotrzeć ponownie, nawet jeśli odbiorca obsłużył wcześniejsze żądanie.

  1. Sprawdź X-Sellf-Signature na oryginalnej treści żądania.
  2. Sprawdź zgodność X-Sellf-Delivery-Id z podpisanym polem id.
  3. Zapisz identyfikator i wynik obsługi w jednej transakcji bazy odbiorcy.
  4. Dla wcześniej obsłużonego identyfikatora zwróć 2xx bez ponownego wysyłania e-maila lub powtarzania innych czynności.

Nagłówki X-Sellf-Event i X-Sellf-Signature nadal obowiązują. Podpis ma postać t=<sekundy_unix>,v1=<HMAC-SHA256> i obejmuje <t>.<oryginalna_treść>, w tym pole id. Przy ponowieniu podpis jest obliczany ponownie. Pole timestamp w zapisanym payloadzie pozostaje stałe.

Każda pozycja purchase.completed.licenses[] zawiera expiresAt: datę ISO 8601 UTC albo null dla licencji bezterminowej. Odbiorca nie musi dekodować tokenu.

Dla zakupów purchase.completed istnieje jedna logiczna dostawa na zamówienie/zdarzenie/endpoint. Nowy zakup otrzymuje nowy identyfikator dostawy. Subskrypcje wysyłają invoice.paid; każda faktura stanowi osobne zamówienie. Błąd wystawiania licencji lub przerwana realizacja mogą zostać uzupełnione przez kolejne zdarzenie lub weryfikację zakupu. Zapis zakończonej transakcji nie oznacza, że wszystkie dostawy już się zakończyły.

Zamówienie przelewem opłacone kartą ze strony zamówienia wysyła purchase.completed z order.settledVia: "stripe" i order.paymentIntentId Stripe (do uzgodnienia płatności i zwrotu); przelew zaksięgowany przez sprzedawcę ma settledVia: "bank_transfer" i paymentIntentId: null. customer.firstName / lastName są uzupełniane z kupującego zapisanego w orderDetails.buyer.

purchase.completed zawiera attribution, gdy zamówienie ma zapisane źródło (Źródła zakupów): kanał, ostatni i pierwszy kontakt, urządzenie, kraj i typ identyfikatora kliknięcia — nigdy sam identyfikator.

Pełny katalog zdarzeń, przykłady danych VAT i licencji oraz konfiguracja ponowień znajdują się w dokumentacji webhooków po angielsku.

Obiekt invoice w purchase.completed i invoice.paid zawiera obok nip pola taxIdType (pl_nip, eu_vat, other) i taxIdCountry, wyznaczane z kraju firmy; bez identyfikatora oba mają wartość null. Koszyk z profilem zapisuje też w orderDetails.buyer pola tax_id_type, tax_id_country i, przy włączonym VIES, tax_id_vies.

invoice.paid wiąże data.invoice.stripeInvoiceId z data.subscription.stripeSubscriptionId, data.product.id i data.customer.userId. invoice.orderId i invoice.orderNumber wskazują zamówienie Sellf przypisane do tej faktury; invoice.stripeInvoiceId pozostaje identyfikatorem Stripe. Faktura zawiera amountPaid (główna jednostka waluty), currency i paidAt. subscription.currentPeriodStart oraz subscription.currentPeriodEnd (ISO 8601 UTC) pochodzą z konkretnej opłaconej pozycji subskrypcyjnej tej faktury. Jeśli nie ma jednoznacznej pozycji bez proporcjonalnego rozliczenia z prawidłowym okresem, pola są pomijane. Odbiorca nie powinien wyliczać opłaconego dostępu z daty dostawy ani z późniejszej aktualizacji subskrypcji.

payment.orderNumber to numer zamówienia Sellf zwracanej płatności (null, gdy nie jest dostępny); payment.id pozostaje identyfikatorem transakcji Sellf.

refund.issued przekazuje data.refund.stripeRefundId i rzeczywisty status Stripe: pending, requires_action, succeeded, failed albo canceled. Potwierdzenie pełnego zwrotu wymaga statusu succeeded, isFullRefund: true i totalRefunded >= payment.amount przy dodatniej kwocie płatności. Kwoty są w najmniejszych jednostkach waluty. refund.issued powstaje dokładnie raz na ID zwrotu, z pełną kwotą tego zwrotu i rzeczywistym statusem. Każda późniejsza zmiana statusu wysyła osobne refund.updated: stripeRefundId, previousStatus, status, statusVersion, pełne amount, currency, totalRefunded, isFullRefund oraz payment.statusAfter. Zmiana statusu nie oznacza kolejnej korekty faktury; dane VAT dotyczą refund.issued. Rejestr zmian i unikalny klucz dostawy na endpoint/wersję eliminują identyczne potwierdzenia. Odbiorca powinien zachować najwyższe statusVersion dla ID zwrotu i pomijać starsze wersje, ponieważ dostawy i ponowienia mogą nadejść w innej kolejności. Częściowy zwrot ustawia partially_refunded w DB, API płatności, panelu i payloadzie. GET /api/v1/payments/{id} zwraca refund.id, refund.status (null, jeśli nie został zaobserwowany) i łączną kwotę refund.amount.

Dla subscription.canceled i subscription.updated pole endedAt oznacza faktyczne ended_at Stripe, a canceledAt — moment anulowania lub złożenia takiego żądania. endsAt oznacza termin dostępu: przy anulowaniu bez zwrotu jest to koniec okresu potwierdzonego pozycją opłaconej faktury, również gdy Stripe kończy subskrypcję od razu. Nieopłacone odnowienie nie przedłuża terminu. Bez potwierdzonego okresu natychmiastowe anulowanie używa ended_at lub canceled_at, a zaplanowane podaje null. Aktualizacje zakończonej subskrypcji lub zaplanowanego anulowania przekazują ten sam termin w currentPeriodEnd. Zwrot kończy dostęp od razu; endedAt nadal opisuje moment zakończenia subskrypcji w Stripe, niezależnie od terminu dostępu.

subscription.updated.previousAttributes zawiera wyłącznie poprzednie wartości znormalizowanych pól, które się zmieniły: status, cancelAtPeriodEnd, cancelAt, canceledAt, endedAt, trialEnd, currentPeriodStart, currentPeriodEnd, quantity, stripePriceId (camelCase, daty ISO 8601 UTC), a changedFields wymienia ich nazwy. Surowe obiekty Stripe (items, plan, faktury) nie są przekazywane. Zmiana pól spoza tej listy daje puste changedFields.

subscription.renewal_upcoming przychodzi 3 dni przed odnowieniem (invoice.nextPaymentAttempt albo koniec okresu). Stripe zapowiada nadchodzącą fakturę, gdy tylko odnowienie wejdzie w okno konta, na wielu kontach zaraz po zakupie, również przy 7-dniowej próbie, dlatego Sellf zapisuje zapowiedź i wysyła ją w terminie. Subskrypcja anulowana, ustawiona na anulowanie z końcem okresu albo już nieaktywna nie dostaje zapowiedzi. Gdy do odnowienia zostały najwyżej 3 dni, zapowiedź idzie od razu.

Gdy subskrypcja kończy się bez zwrotu, istniejący dostęp i licencje jej faktur wygasają z końcem opłaconego okresu, emitując access.expired i license.expired. Zmiana terminu licencji emituje license.updated. Wydane tokeny zachowują podpis: odbiorca musi odświeżać CRL, która uwzględnia zamówienia po upływie terminu z rejestru. Pełny lub częściowy zwrot po anulowaniu odbiera dostęp i odwołuje licencje od razu, również gdy zwrot przychodzi później. Saldo kredytowe lub oczekujące rozliczenie proporcjonalne samo nie potwierdza zwrotu pieniędzy; rejestr zwrotów aktualizują webhooki Stripe. Spór nadal zawiesza dostęp od razu. Subskrypcje zakończone bez zapłaty (unpaid albo incomplete_expired) zachowują access.revoked / license.revoked z revocationReason: "expired".

Podpisane dispute.created i dispute.closed działają dla wszystkich produktów, niezależnie od licencji i license.revoked. Na istniejącym endpoincie Stripe włącz charge.dispute.created oraz charge.dispute.closed; nowe endpointy Sellf zawierają je automatycznie.

data.dispute zawiera stripeDisputeId, stripeChargeId, rzeczywisty status Stripe (m.in. needs_response, won, lost), reason, amount w najmniejszych jednostkach, currency i createdAt (ISO 8601 UTC). data.payment zawiera id transakcji Sellf, sessionId, paymentIntentId, stripeInvoiceId, subscriptionId, kwotę i walutę zakupu. data.product.id i data.customer.userId / email wiążą zdarzenie z produktem i klientem. Dla subskrypcji dochodzi data.subscription.id oraz stripeSubscriptionId, jeśli jest dostępny.

accessRevoked i accessRestored opisują wynik zapisanej obsługi sporu. Otwarcie i przegrany spór zawieszają dostęp. Po won płatność wraca do wcześniejszego stanu (completed lub partially_refunded), a uprawnienie wraca z zachowanym terminem. accessRestored: true oznacza rzeczywiście przywrócony dostęp; pełny zwrot, ręczne usunięcie grantu, upływ terminu lub zakończenie subskrypcji blokują odtworzenie. Gość odzyskuje oryginalny nieodebrany zakup. Zapisany termin obowiązuje również przy późniejszym odebraniu, także po zmianie czasu dostępu w produkcie. Ponowienie zdarzenia nie przedłuża terminu. Wygrana usuwa również odwołanie licencji zapisanych jako cofnięte przez ten spór. licenseRestored i restoredLicenses opisują faktycznie zmienione licencje, z tym samym tokenem i terminem. Ręczne cofnięcie lub zwrot blokują przywrócenie. Licencje cofnięte przed wprowadzeniem zapisu pochodzenia nie są przywracane automatycznie. Odbiorca powinien używać flagi accessRestored oraz payment.statusAfter, a nie samego wyniku won. dispute.restoredAccess wymienia faktycznie przywrócone uprawnienia: productId, userId (null dla gościa), grantedAt i expiresAt (null dla dostępu bezterminowego). Dla gościa dochodzi guestPurchaseId. Odbiorca powinien zastosować tę listę: ręcznie usunięty grant głównego produktu może pozostać nieobecny, gdy dostęp do dodatku wróci.

license.issued / license.expired / license.updated — Pro

Dział zatytułowany „license.issued / license.expired / license.updated — Pro”

license.issued.customer zawiera email oraz userId (null dla gościa).

license.issued przychodzi raz dla każdej licencji zapisanej w Sellfie, niezależnie od ścieżki: zakup, darmowy produkt, ręczne wydanie w panelu albo POST /api/v1/licenses (license.issuanceSource: purchase, manual lub api). license.expired przychodzi raz, gdy aktywna licencja minie expiresAt (sprawdzane co 30 sekund w cyklu zdarzeń); licencja odwołana nie wygasa drugi raz. license.issued zawiera dodatkowo licenseKey, czyli podpisany klucz do przekazania kupującemu. Inne zdarzenia cyklu licencji nie zawierają tokenu. Nie zapisuj klucza w logach aplikacji. Subskrypcja i wysyłka zdarzeń licencji nadal wymagają Pro. Opcja sendEmail przy ręcznym wydaniu lub wydaniu przez API uwzględnia przełącznik sklepu. Zobacz Maile do kupujących dla zasad wysyłki.

Licencja wydana dla zamówienia z otwartym albo przegranym sporem zapisuje się jako odwołana przez ten spór: dostajesz license.issued, a po nim license.revoked z dispute.stripeDisputeId; purchase.completed.licenses[] jej nie zawiera. Wygrany spór ją przywraca (license.restored).

license.updated informuje o zmianie terminu wygaśnięcia, również przy anulowaniu bez zwrotu. Pole license.expiresAt podaje termin z rejestru; podpisany token pozostaje ten sam.

Pełny zwrot, anulowanie zamówienia i chargeback cofają wszystkie licencje zamówienia, także dodatków order bump i składników zestawu. Każda cofnięta licencja ma własne zdarzenie license.revoked. Dotyczy to również quick-pay i przelewów rozliczonych offline. Częściowy zwrot pozostawia licencje aktywne. Podpisane wartości license.order i ich hashe w CRL pozostają bez zmian.

Każda rzeczywista zmiana stanu odwołania tworzy trwałe powiadomienie. Powtórzenie niezmienionego statusu nie dodaje zdarzenia. Subskrypcja i wysyłka obu typów wymagają funkcji Pro; sam stan licencji zmienia się niezależnie od bieżącego planu sklepu.

Dane obejmują license.id, order, email, tier, domain, issuanceSource, issuedAt, expiresAt, revokedAt, produkt i crlUrl. license.order to surowy identyfikator podpisany w tokenie (płatność pi_…, sesja checkoutu, faktura odnowienia in_…, ID zamówienia offline albo api_…); license.orderId i license.orderNumber wskazują zamówienie Sellf (null przy ręcznym lub API wydaniu bez zamówienia). Pola te mają wszystkie zdarzenia license.*. revocationReason (na górze danych i w license.revocationReason) mówi, dlaczego licencja przestała działać: refund (pełny zwrot), dispute, manual (panel albo DELETE /api/v1/licenses/{id}) , subscription_cancelled lub expired (subskrypcja zakończona bez zapłaty); dla aktywnej licencji ma wartość null. Wygaśnięcie to osobne license.expired. Przywrócenie dodaje license.restoredAt, a powiązany spór — dispute.stripeDisputeId. Token nie jest wysyłany. Po usunięciu odwołania można używać tego samego tokenu; wygasły pozostaje wygasły.

Po każdym zdarzeniu usuń lokalny cache odpowiedniego zakresu CRL, pobierz aktualną listę i sprawdź podpis oraz pierwotny termin tokenu. Endpoint CRL zwraca Cache-Control: no-store. Przywrócenie nie przedłuża terminu. Aby licencja pozostała cofnięta także po wygraniu sporu, wybierz Pozostaw licencję cofniętą w ustawieniach wydanych licencji. Cofnięcia ze starszych wersji nie mają zapisanego powiązania ze sporem i wymagają osobnej decyzji sprzedawcy.

Sellf zapisuje dostawę przed pierwszą próbą i wysyła ją od razu. Dotyczy to również przycisku Wyślij test: test ma jedną próbę, bez automatycznych ponowień. Historia dostaw domyślnie pokazuje wszystkie statusy. Filtr nieudanych dostaw obejmuje również oczekujące ponowienia i dostawy po wyczerpaniu prób.

Ponowienia nieudanych lub przerwanych zwykłych dostaw wymagają osobnego zadania uruchamianego co minutę. Samo uruchomienie aplikacji przez PM2 go nie ustawia. Ustaw SELLF_URL i CRON_SECRET w środowisku harmonogramu, a następnie dodaj:

* * * * * curl -fsS -H "Authorization: Bearer $CRON_SECRET" "$SELLF_URL/api/cron?job=webhook-deliveries-retry" > /dev/null

To osobne zadanie od affiliate-sync. Kontroluj błędy wywołań w logach harmonogramu. Brak harmonogramu wstrzymuje ponowienia, ale nie pierwszą próbę ani zapis logów. Ręczne ponowienie starej dostawy o statusie failed aktualizuje ten sam wpis, zachowując identyfikator dostawy.

Włącz checkout.session.expired na endpoincie Stripe wysyłającym zdarzenia do /api/webhooks/stripe, obok zdarzeń zakończenia płatności. Nowe endpointy tworzone w ustawieniach Sellf mają je automatycznie. Dla istniejącego endpointu dodaj to zdarzenie w Stripe Dashboard → Workbench → Webhooks → endpoint → Edit events.

Po zmianie koszyka lub opuszczeniu checkoutu przed potwierdzeniem płatności Sellf wygasza poprzednią Checkout Session i zmienia status jej oczekującej transakcji na abandoned. Powrót przyciskiem „Wstecz” przywraca pierwszy krok; nowa sesja powstaje dopiero po wybraniu „Przejdź do płatności”. Przekierowanie podczas potwierdzania płatności zachowuje aktywną sesję. Naturalne wygaśnięcie uruchamia tę samą zmianę przez zdarzenie Stripe. Zakończone transakcje pozostają bez zmian, a powtórne zdarzenia można obsłużyć ponownie. Błąd zapisu zwraca HTTP 500, aby Stripe ponowił dostawę.

Jeśli przeglądarka zamknie stronę przed otrzymaniem odpowiedzi tworzącej sesję, nie może później wysłać żądania jej zamknięcia — nawet z opcją keepalive. Zdarzenie wygaśnięcia musi być włączone, aby rozliczyć takie próby. Gdy strona nadal działa, kolejka czeka z zamknięciem na zakończenie tworzenia sesji. Sellf zachowuje też sesje, których PaymentIntent jest przetwarzany, czeka na pobranie środków lub dodatkowe działanie klienta albo zakończył się powodzeniem.

Każdy purchase.completed zawiera data.order.orderId (trwały UUID płatności Sellf) i orderNumber, zarówno dla Stripe, jak i przelewu. sessionId i paymentIntentId pozostają identyfikatorami operatora; nie zastępują UUID obsługiwanego przez GET /api/v1/payments/{id}. Szczegóły płatności zawierają również operatora, numer zamówienia, termin, instrukcje przelewu, dane zamówienia, pozycje oraz podsumowanie kuponu i faktury dostępne na liście płatności.

purchase.completed oraz order.placed, order.cancelled, order.overdue, order.abandoned mają data.amountUnit = "minor". Wszystkie zdefiniowane kwoty są w najmniejszych jednostkach waluty: order.amount/grossTotal/netTotal/taxTotal, price/net/tax/gross produktu, dodatków i składników pakietu oraz lines[].unit_price/total_price/discounted_total/net_amount/tax_amount/gross_amount. Cena jednostkowa nadal opisuje jedną sztukę; snapshot VAT i suma zamówienia uwzględniają ilość. Dla PLN/USD mnożnik wynosi 100, a JPY nie ma części ułamkowej. Ilość i procent VAT nie są kwotami. Te jednostki webhooków różnią się od zapisanych cen pozycji zwracanych przez API płatności v1.

Zamówienie zawsze podaje taxSnapshotStatus: none, captured, partial, unavailable lub local. Nieznane netto/VAT mają wartość null, zamiast zmyślonego zera. grossTotal to zapisana kwota płatności. vatRate jest procentem albo null; unavailable nie oznacza zwolnienia z VAT.

Zdarzenia przelewu order.* zawierają access.policy (on_placement albo after_payment) i access.grants[]: productId, status, grantedAt, expiresAt. Stany to granted, pending_confirmation, pending_payment, expired albo revoked. Daty pochodzą z zapisanego dostępu; dla oczekującego grantu nie zostały jeszcze nadane. null końca nadanego dostępu oznacza dostęp bezterminowy.

Zdarzenie Dane potrzebne odbiorcy
order.abandoned Porzucona oczekująca płatność: ID zamówienia i operatora, stary/nowy stan, klient, kwota i VAT. customer.email ma wartość null, gdy kupujący nie podał adresu.
seats.held Rezerwacja miejsc: ID rezerwacji, zamówienia, produktu, terminu/progu cenowego, data i liczba miejsc.
seats.confirmed Potwierdzenie miejsc: te same identyfikatory oraz poprzedni i nowy stan.
seats.released Zwolnienie miejsc: te same dane i powód (order_abandoned, order_cancelled, payment_refunded, hold_expired, reservation_released).
access.granted Nadanie dostępu, również darmowego, po zakupie oraz po przejęciu zakupów gościa.
access.updated Zmiana zapisanych dat lub źródła dostępu, również ręczne przedłużenie.
access.revoked Usunięcie grantu wraz z faktycznym czasem odebrania i revocationReason.
access.expired Upłynięcie zapisanego końca dostępu: jeden komunikat na grant/datę końca, także po odnowieniu.

Każde zdarzenie przelewu order.* ma w data.order dodatkowo: status, payUrl (podpisany link do strony zamówienia: stan, dane przelewu, przycisk „Wysłałem przelew”, ważny do payUrlExpiresAt), reservation (timed — rezerwacja czasowa, invoice — faktura wystawiona, czeka na płatność bez wygasania, none), reminderAt, releaseAt, invoiceHoldAt, transferDeclaredAt, transferDeclaredNote, cancelReason, cancelReasonText, reopenedAt, a data.customer.locale podaje język kupującego (pl/en). Z tych pól integrator wystawia u siebie proformę, fakturę lub własny mail (n8n, Listmonk). Każde zdarzenie jest dostarczane raz na zamówienie.

Zdarzenie Kiedy Co odbiorca może zrobić
order.placed Złożenie zamówienia na przelew. Potwierdzenie z payUrl; releaseAt to termin rezerwacji wydarzenia.
order.payment_reminder Minął reminderAt (domyślnie 24 h) bez wpłaty i bez faktury. Przypomnienie „zapłać do releaseAt” z linkiem.
order.transfer_declared Kupujący kliknął „Wysłałem przelew” (raz). Sprawdzenie wyciągu; releaseAt jest już przedłużone (domyślnie o 72 h).
order.invoice_issued Dla nieopłaconego zamówienia wystawiono fakturę (w Sellf albo POST /api/v1/payments/:id/invoice-issued). Status „faktura wystawiona, czeka na płatność”: reservation = invoice, releaseAt = null, brak wygasania.
order.cancelled Anulowanie: cancelReason = payment_window_expired (automatycznie po releaseAt) albo admin z tekstem administratora w cancelReasonText. reservation = none, reminderAt/releaseAt mają wartość null. customer.userId jest taki sam jak w seats.released. Informacja dla kupującego, korekta faktury; lateTransferPolicy = admin_decision.
order.overdue Minął termin płatności zamówienia bez rezerwacji czasowej. Ponaglenie.
order.reopened Administrator przyjął przelew, który doszedł po anulowaniu (po cenie z zamówienia, także ponad limit miejsc). Powiązanie wpłaty: previousStatus = cancelled; zaraz po nim purchase.completed.
order.participants_updated Kupujący uzupełnił listę uczestników po zapłacie (opcja produktu „uzupełnię później”). Wysyłane raz na zamówienie. orderDetails.participants.people zawiera pełną listę (first_name, last_name, email), orderDetails.quantity.value liczbę; purchase.completed miało pustą listę.

Rezerwacja czasowa dotyczy wydarzeń i jest ustawiana przez sprzedawcę (Ustawienia → Płatności → Przelew tradycyjny). Zwykłe produkty nie wygasają. Zaplanuj /api/cron?job=transfer-reservations co 5 minut.

Zdarzenie dostępu podaje customer, product, access.id, grantedAt, expiresAt, statusBefore/statusAfter, reason i actor (user, api_key albo system; dla systemu ID jest null). access.granted i access.updated podają też grantSource: skąd pochodzi dostęp, zapisane raz przy nadaniu (purchase, bundle, bank_transfer, subscription, free, manual albo unknown dla nadań starszych niż to pole). Używaj grantSource zamiast reason: reason zostaje bez zmian dla istniejących integracji, ale bywa wywnioskowane (np. free_product z ceny), więc płatny produkt odebrany z kuponem 100% ma grantSource: "free". Pola główne accessGrantedAt/accessExpiresAt zawierają te same zapisane daty. access.granted i access.updated podają też accessEndsAt: zapisany koniec dostępu, a dla subskrypcji koniec bieżącego opłaconego okresu (null przy dostępie bezterminowym). Subskrypcja wysyła access.updated (reason: "subscription_renewed") raz na odnowiony okres; powtórzone zdarzenia Stripe dla tego samego okresu nie dają kolejnych aktualizacji. access.revoked i access.expired podają revocationReason: refund, dispute, manual, subscription_cancelled albo expired (subskrypcja zakończona bez zapłaty lub naturalny koniec). reason zachowuje dotychczasowe znaczenie (skąd był dostęp: purchase, subscription…). sourceOrders zawiera powiązane zapisane zamówienia; sourceOrder jest wypełnione tylko przy jednym jednoznacznym zamówieniu. Ręczne lub niepowiązane granty mogą nie mieć zamówienia. occurredAt opisuje zmianę, a timestamp koperty przygotowanie dostawy. Nie należy wyliczać dostępu ze stanu płatności ani z chwili odebrania webhooka — służą do tego jawny stan i zapisane daty.

Zmiany są zapisywane transakcyjnie i trafiają do podpisanej kolejki ze stabilnym kluczem. Ponowienie zachowuje ID dostawy — odbiorca deduplikuje po tym ID. Długotrwały proces produkcyjny obsługuje zmiany i wygaśnięcia co 30 sekund; build i testy nie uruchamiają tego harmonogramu. W środowisku serverless trzeba zaplanować uwierzytelniony /api/cron?job=business-events. Dotychczasowe zadanie access-expired korzysta z tego samego producenta. Zadanie ponowień dostaw webhooków nadal powinno być skonfigurowane na wypadek przejściowych błędów HTTP.

Kolejność dostaw pomiędzy workerami i ponowieniami nie jest gwarantowana. Stan grantu aktualizuj według occurredAt, pomijając starszą zmianę odebraną później.

Podstawienie {{order_id}} preferuje wewnętrzny UUID, gdy jest dostępny; identyfikatory operatora i dotychczasowe klucze dostaw pozostają bez zmian.

Darmowy checkout waliduje wartości według tych samych definicji produktu co płatny. Przed wysłaniem linka wartości trafiają do prywatnego kontekstu żądania. Link zawiera losowy UUID, a nie domenę ani inne odpowiedzi. Po potwierdzeniu kontekst jest powiązany ze zweryfikowanym adresem klienta i produktem. Pending grant przy innym logowaniu korzysta z tego samego zapisu; nie zależy od edytowalnego user_metadata ani nie umieszcza odpowiedzi w tokenie uwierzytelnienia.

Dostęp zachowuje custom_field_values, a access.* i lead.captured podają znormalizowany snapshot jako customFieldValues. Zapis trafia do wystawiania licencji, także dla _sellf_license_domain. Ponowne potwierdzenie zachowuje klucz free_<userId>_<productId> i dotychczasowy token licencji. Konteksty oczekujące mają ważność 30 dni; przejęte są czyszczone po jednym dniu, lecz snapshot w grancie pozostaje.

Ręczne wystawianie również respektuje definicję produktu: pole domeny wymagane musi być wypełnione, opcjonalne może zostać pominięte, a produkt bez takiego pola otrzymuje token bez claims.domain. Brak wymaganych wartości zwraca HTTP 400 przed podpisaniem.

Te zdarzenia zapisują się w tej samej transakcji co zmiana (jak zdarzenia dostępu) i idą tą samą podpisaną kolejką. Każde ma actor, occurredAt i (poza wypłatami) product. Kwoty są w jednostkach mniejszych (amountUnit = "minor", czyli grosze dla PLN). Ponowione z kolejki zdarzenie ma ten sam klucz dostawy, więc odbiorca dostaje je raz; mimo to deduplikuj po id koperty.

Zdarzenie Kiedy Pola do decyzji odbiorcy
invoicing.issued Dostawca (Fakturownia) wystawił fakturę sprzedaży. invoice.id/number/providerInvoiceId/viewUrl/attempt/paymentSynced, order (ID, numer, kwota, waluta), customer.
invoicing.failed Próba wystawienia się nie udała. Raz na próbę. invoice.attempt, invoice.error (komunikat dostawcy), invoice.willRetry (false po 5. próbie).
invoicing.corrected Wystawioną fakturę oznaczono jako skorygowaną. invoice.number, statusBefore/statusAfter, order.
commission.accrued Partner zarobił prowizję od opłaconego zamówienia. partner (memberId, code, displayName, status), commission.amount/currency/baseAmount/eligibleAt/paidAt/livemode, order.
commission.reversed Zwrot cofnął (część) prowizji. commission.amount jest ujemne; te same identyfikatory.
payout.reserved Właściciel zatwierdził prowizje do wypłaty (rezerwacja). payout.id/amount/currency/cutoff/payeeReference/commissionIds, partner. product = null.
payout.paid Wypłatę oznaczono jako zapłaconą. payout.bankReference/invoiceReference/bankAmount/paidAt.
payout.cancelled Zarezerwowaną wypłatę anulowano; prowizje wracają do salda. payout.statusBefore = "reserved".
refund.requested Kupujący złożył prośbę o zwrot. refundRequest.id/requestedAmount/currency/reason, order, customer.
refund.request_approved / refund.request_rejected / refund.request_cancelled Prośbę rozpatrzono albo wycofano. refundRequest.statusBefore/statusAfter/adminResponse/processedAt. Sam zwrot pieniędzy to refund.issued.
product.published / product.unpublished Zmienił się is_active albo utworzono/usunięto aktywny produkt. product (id, slug, isActive, availableFrom/Until, productType), availability.before/after, deleted.
product.price_changed Zmieniła się cena, cena promocyjna, koniec promocji, cena cykliczna albo waluta. price.before/after: price, salePrice, salePriceUntil, recurringPrice, currency w jednostkach mniejszych.
product.sold_out Miejsca wstrzymane (niewygasłe) i potwierdzone osiągnęły pojemność terminu wydarzenia. session.id/label/startsAt/capacity/taken/remaining, reservation, która go wypełniła. Zwolnione później miejsca zgłasza seats.released.

actor to zalogowany administrator (user) albo klucz API (api_key) przy zmianach z panelu lub API v1, a system przy zmianach automatycznych (synchronizacja, zadania cykliczne; działania kupującego zgłaszają user). Prośba o zwrot cofnięta do pending po nieudanym zwrocie w Stripe jest ogłaszana ponownie jako refund.requested ze statusBefore = "approved".

Prowizja partnera staje się wypłacalna, gdy minie eligibleAt; Sellf nie wysyła osobnego zdarzenia na ten moment, punktem zatwierdzenia jest payout.reserved. Okna publikacji (availableFrom/Until) są w treści, ale sam upływ czasu nie generuje zdarzenia.

Formularze potwierdzane mailem i zgoda marketingowa.

Zobacz Maile do kupujących. Kwoty są w najmniejszych jednostkach waluty.

Zdarzenie Dane do zbudowania maila
order.placed, order.payment_reminder customer.email/locale, order.transfer (odbiorca, konto, bank, tytuł), order.amount/currency, order.paymentDeadline, order.payUrl, terminy rezerwacji i pozycje zamówienia.
order.cancelled Identyfikator zamówienia, order.cancelReason i order.cancelReasonText.
purchase.completed Kupujący, produkty, kwota, zamówienie i order.settledVia; potwierdzenie płatności Stripe lub przelewu. customer.locale i buyerMail.event_date/event_online_url odpowiadają danym maila Supabase; adres wydarzenia tylko przy aktywnym dostępie.
order.participants_needed Email i język kupującego, produkt (id/nazwa/slug), zamówienie (id/numer/kwota/waluta/status), orderDetails, reminder.stage (1: po 24 h; 2: dwa dni przed wydarzeniem), reminder.participantsUrl (osobisty link). Stały identyfikator dostawy na zamówienie i etap. Standardowe zasady rejestracji webhooków, bez dodatkowej bramki Pro.
license.issued licenseKey, kupujący, produkt, wariant, ważność i zamówienie. Dotychczasowa bramka Pro pozostaje.

Link uczestników i klucz licencji przekazuj wyłącznie właściwemu kupującemu. Sprawdzaj podpis webhooka i nie zapisuj tych danych w logach aplikacji. Kolejka szyfruje treść wydania licencji i powiadomienia o uczestnikach kluczem APP_ENCRYPTION_KEY instancji; widok logów pokazuje zaszyfrowany zapis.

data.customer.locale jest zawsze obecne (pl lub en) w purchase.completed, license.issued, order.placed, order.payment_reminder, order.cancelled, order.participants_needed, refund.issued, lead.captured, waitlist.signup, access.expired oraz zdarzeniach subskrypcji zawierających kupującego. Język pochodzi z danego zamówienia, transakcji, subskrypcji lub leada, a nie z innego zakupu pod tym samym adresem email. Starsze dane bez zapisanego języka korzystają z języka sklepu: shop_config.custom_settings.default_locale (pl lub en, ustawiane przez API konfiguracji sklepu). Przy braku ustawienia obowiązuje domyślny język aplikacji. Żądanie zapisu na listę oczekujących przyjmuje opcjonalne locale o tych samych wartościach. Ponowienie dostawy zachowuje pierwotny język. Wybór pól w konfiguracji endpointu może celowo pomijać pola kupującego. Potwierdzenie leada produktu emituje jedno lead.captured: identyfikator leada, źródło, zgoda i daty potwierdzenia trafiają do tego samego zdarzenia co szczegóły produktu, daty dostępu, własne pola oraz wydana licencja. Ponowne potwierdzenie tego samego leada zachowuje klucz dostawy. Zapis na samą listę zachowuje pola leada i zgody bez dostępu do produktu.