eZif anunță aplicația (POST, JSON) pe adresa de webhook a cheii, înregistrată de aplicație cu POST /callback ({"url": "https://…"}; răspunsul conține secretul cu care eZif semnează). Se trimit doar evenimentele bifate în setările aplicației.
Antete
| Antet | Valoare |
|---|---|
X-Ezif-Event |
evenimentul (ex. proforma.paid) |
X-Ezif-Delivery |
id-ul livrării (ex. d_812); același și în corp (delivery). O livrare repetată (reîncercare, Retrimite) are același id: aplicația o ignoră dacă a procesat-o deja |
X-Ezif-Timestamp |
secunde Unix |
X-Ezif-Signature |
HMAC-SHA256 hex cu secretul de callback, peste timestamp + . + corpul exact primit |
Aplicația răspunde 2xx (nu o pagină HTML). Altfel eZif reîncearcă după 1 min, 5 min, 15 min, 1 h, 3 h, 12 h, apoi marchează livrarea „eșuată”. Integrări → API și chei → Livrări webhook (30 de zile) arată fiecare livrare, cu Retrimite.
Evenimente
| Eveniment | Când | Conținut principal |
|---|---|---|
proforma.created |
proforma emisă | proforma (id, number_text, external_id, total, valid_until, pay_url, pdf_url) |
proforma.partially_paid |
încasare parțială | proforma, payment, paid_total, remaining |
proforma.paid |
plata integrală (factura emisă) | proforma, payment, paid_total, invoice (id, number_text, total, pdf_url) |
proforma.expired · proforma.cancelled |
expirare / anulare | proforma, reason |
invoice.issued |
factura emisă (și cea automată, din proformă) | invoice (id, number_text, total, from_proforma_id, external_id, pdf_url) |
invoice.paid · invoice.payment · invoice.payment_cancelled |
încasările pe factură | ca în API-ul extern |
invoice.spv_accepted · invoice.spv_rejected |
rezultatul ANAF | invoice, spv (upload_index, download_id, env) |
invoice.storno |
stornarea facturii | invoice_id, credit_note, reason |
{"event": "proforma.paid", "delivery": "d_812", "occurred_at": "2026-10-03T09:12:44+00:00", "sent_at": "2026-10-03T09:12:45+00:00",
"proforma": {"id": 9012, "number_text": "PJPF00042", "external_id": "PJAPI-SUB-1842-2026-10", "total": "301.29", "status": "invoiced"},
"payment": {"amount": "301.29", "method": "online", "reference": "ord_7f3c…", "paid_on": "2026-10-03"}, "paid_total": "301.29",
"invoice": {"id": 9013, "number_text": "PJ00118", "total": "301.29", "from_proforma_id": 9012, "pdf_url": "https://app.ezif.ro/api/public/documente/…"}}
Verificarea în aplicație (PHP)
$raw = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_EZIF_TIMESTAMP'] ?? '';
$ok = hash_equals(hash_hmac('sha256', $ts . '.' . $raw, CALLBACK_SECRET), $_SERVER['HTTP_X_EZIF_SIGNATURE'] ?? '');
if (!$ok || abs(time() - (int) $ts) > 300) { http_response_code(401); exit; }
$e = json_decode($raw, true);
if (already_processed($e['delivery'])) { http_response_code(200); exit; } // livrare repetată
// ex. proforma.paid → activează / prelungește abonamentul $e['proforma']['external_id']
http_response_code(200);