Configurare webhooks — URL, events si verificare semnatura

Webhooks-urile permit aplicatiei tale să primeasca notificări în timp real când au loc evenimente în SoftFactura — factura creată, plata înregistrată, e-Factura acceptată sau respinsă. În loc să intrebi periodic API-ul (polling), SoftFactura trimite un HTTP POST către URL-ul tau la fiecare eveniment.

Configurare webhook

1. Mergi la Dezvoltatori din meniul lateral.
2. Selectează tab-ul Webhooks.
3. Apasă Webhook nou.
4. Completează:
   • URL — adresa HTTPS către care SoftFactura va trimite notificările (ex: https://erp.firma-ta.ro/webhooks/softfactura).
   • Evenimente — selectează evenimentele la care vrei să fii notificat.
5. Apasă Creează.
6. SoftFactura generează un secret unic pentru verificarea semnaturii — copiază-l și salvează-l în aplicația ta.

Evenimente disponibile

Eveniment	Când se declanșează
invoice.created	Factura nouă creată
invoice.issued	Factura emisă (trece din ciorna în emisă)
invoice.paid	Factura marcata ca plătită integral
invoice.cancelled	Factura anulată sau stornata
payment.received	Plata înregistrată pe o factura
client.created	Client nou creat
client.updated	Date client actualizate
product.created	Produs/serviciu creat
product.updated	Produs/serviciu actualizat
efactura.sent	e-Factura trimisă la ANAF
efactura.accepted	e-Factura acceptată de ANAF
efactura.rejected	e-Factura respinsă de ANAF

Format payload

Fiecare notificare este un POST cu body JSON:

{
  "event": "invoice.paid",
  "data": {
    "id": "inv_abc123",
    "series": "SF",
    "number": 42,
    "total": 5950.00,
    "currency": "RON",
    "status": "paid",
    "client": { "id": "cl_xyz", "name": "Firma Client SRL" },
    "paidAt": "2026-04-16T14:30:00Z"
  },
  "timestamp": "2026-04-16T14:30:01Z"
}

Verificare semnatura

Fiecare cerere include un header X-Webhook-Signature cu semnatura HMAC-SHA256 a body-ului, calculată cu secret-ul webhook-ului. Verifică semnatura în aplicația ta pentru a te asigura ca notificarea vine de la SoftFactura:

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return expected === signature;
}

Header-ul X-Webhook-Event contine numele evenimentului (ex: invoice.paid).

Monitorizare livrari

1. În lista Webhooks, click pe webhook-ul dorit pentru a vedea detaliile.
2. Secțiunea Istoric livrari afișează ultimele 10 notificări cu:
   • Eveniment — tipul evenimentului.
   • Status — cod HTTP returnat de serverul tau (200 = succes, altceva = eroare).
   • Data — timestamp-ul livrarii.
3. Dacă o livrare a esuat, verifică ca URL-ul este accesibil și ca serverul tau procesează corect cererile POST.

Bune practici

• Folosește HTTPS — SoftFactura trimite date sensibile (sume, clienti). Nu sunt acceptate URL-uri HTTP.
• Raspunde rapid — procesează notificarea asincron (salveaz-o într-o coada și proceseaz-o în background) și returnează 200 imediat.
• Verifică semnatura — previne procesarea de notificări falsificate.
• Selectează doar evenimentele necesare — nu te abona la toate evenimentele dacă nu le folosești pe toate.