Webhook-uri
PayLinks folosește webhook-uri Stripe pentru a procesa evenimentele de plată în timp real.
URL Webhook
https://paylinks.ro/webhooks/stripe
Acest endpoint este înregistrat la Stripe și primește toate evenimentele relevante pentru conturile conectate.
Tipuri de evenimente
PayLinks procesează următoarele evenimente webhook Stripe:
Evenimente de plată
| Eveniment | Descriere |
|---|---|
payment_intent.succeeded | Plata finalizată cu succes. Creează o înregistrare de tranzacție. |
payment_intent.payment_failed | Plata eșuată. Actualizează statusul tranzacției la FAILED. |
Evenimente de abonament
| Eveniment | Descriere |
|---|---|
customer.subscription.created | Abonament nou creat. |
customer.subscription.updated | Statusul abonamentului s-a schimbat (ex. active, past_due). |
customer.subscription.deleted | Abonament anulat și încheiat. |
invoice.payment_succeeded | Plată recurentă colectată cu succes. |
invoice.payment_failed | Plata recurentă a eșuat. |
Evenimente de dispută
| Eveniment | Descriere |
|---|---|
charge.dispute.created | Dispută nouă deschisă de deținătorul cardului. |
charge.dispute.updated | Statusul disputei s-a schimbat. |
charge.dispute.closed | Dispută rezolvată (câștigată sau pierdută). |
Evenimente de plată către cont
| Eveniment | Descriere |
|---|---|
payout.paid | Plata a ajuns în contul bancar. |
payout.failed | Plata către cont a eșuat. |
Evenimente de cont
| Eveniment | Descriere |
|---|---|
account.updated | Detaliile contului conectat s-au schimbat (verificare, capabilități). |
Verificarea semnăturii
Toate evenimentele webhook sunt verificate folosind semnătura webhook Stripe:
Stripe-Signature: t=timestamp,v1=signature
Handler-ul de webhook verifică semnătura față de secretul webhook înainte de a procesa orice eveniment. Evenimentele cu semnături invalide sunt respinse cu status 400.
Procesarea evenimentelor
Evenimentele sunt procesate sincron pentru fluxurile critice (succes plată, creare dispută) și asincron prin workeri pg-boss pentru operațiunile necritice (actualizări analitice, notificări email).
Idempotență
Toate handler-ele de webhook sunt idempotente. Procesarea aceluiași eveniment de mai multe ori produce același rezultat. Stripe poate livra evenimente de mai multe ori, iar acest lucru este gestionat corespunzător.
Testarea webhook-urilor local
Folosește Stripe CLI pentru a redirecționa webhook-urile către serverul tău local de dezvoltare:
stripe listen --forward-to localhost:4000/webhooks/stripe
CLI-ul afișează un secret de semnare webhook — setează-l ca STRIPE_WEBHOOK_SECRET în fișierul .env.