N. Fattura	Data	Tipo Doc	Cliente / Cedente	Totale	Stato SDI	Azioni

Come funziona la conservazione

I tuoi documenti fiscali (fatture attive e passive) vengono conservati in modo sicuro per tutta la durata del tuo abbonamento. Puoi consultarli, scaricarli singolarmente o esportare l'intero archivio in formato ZIP. In caso di mancato rinnovo dell'abbonamento, avrai 15 giorni per scaricare il tuo archivio completo, trascorsi i quali i dati verranno rimossi dai nostri server. I documenti restano sempre disponibili sul portale Fatture e Corrispettivi dell'Agenzia delle Entrate.

Webhook notifiche real-time

Ricevi notifiche HTTP automatiche quando avvengono eventi sui tuoi documenti conservati (esibizioni pronte, audit, ecc.). Ogni notifica è firmata con HMAC SHA-256.

Nome	URL	Eventi	Stato	Ultima delivery	Azioni
Caricamento...

Documentazione tecnica webhook

Header inviati ad ogni POST

Content-Type:           application/json
User-Agent:             TurboFatturaConservazione/1.0 (webhook)
X-TF-Webhook-Event:     dip.export
X-TF-Webhook-Delivery:  a1b2c3d4e5f6a7b8                  (univoco per dedup)
X-TF-Webhook-Signature: sha256=<hex>                       (HMAC del body)
X-TF-Webhook-Timestamp: 1730729400                        (anti-replay ±300s)

Schema firma HMAC

chiave HMAC = SHA-256(your_secret)         (32 raw bytes)
signature   = "sha256=" + hex(HMAC-SHA256(chiave, raw_body))

Sample receiver completo

<?php
$YOUR_SECRET = 'PASTE_YOUR_SECRET_HERE';
$body = file_get_contents('php://input');
$sig  = $_SERVER['HTTP_X_TF_WEBHOOK_SIGNATURE'] ?? '';
$ts   = (int)($_SERVER['HTTP_X_TF_WEBHOOK_TIMESTAMP'] ?? 0);
if (abs(time() - $ts) > 300) { http_response_code(401); exit('replay'); }
$key = hash('sha256', $YOUR_SECRET, true);
$expected = 'sha256=' . hash_hmac('sha256', $body, $key);
if (!hash_equals($expected, $sig)) { http_response_code(401); exit('bad sig'); }
$payload = json_decode($body, true);
// Idempotenza: dedup su X-TF-Webhook-Delivery
// Tua logica qui: $payload['event'], $payload['payload']
http_response_code(200);
echo '{"ok":true}';

const crypto = require('crypto');
const express = require('express');
const app = express();
app.use(express.raw({ type: '*/*' }));

const YOUR_SECRET = process.env.TFCONS_WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
  const sig = req.headers['x-tf-webhook-signature'] || '';
  const ts  = parseInt(req.headers['x-tf-webhook-timestamp'] || '0', 10);
  if (Math.abs(Date.now()/1000 - ts) > 300) return res.status(401).end();
  const key = crypto.createHash('sha256').update(YOUR_SECRET).digest();
  const expected = 'sha256=' + crypto.createHmac('sha256', key)
    .update(req.body).digest('hex');
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
  if (!ok) return res.status(401).end();
  const payload = JSON.parse(req.body.toString());
  // Tua logica: payload.event, payload.payload
  res.json({ ok: true });
});
app.listen(3000);

import hashlib, hmac, json, os, time
from flask import Flask, request, jsonify

app = Flask(__name__)
YOUR_SECRET = os.environ['TFCONS_WEBHOOK_SECRET']

@app.post('/webhook')
def receive():
    sig = request.headers.get('X-TF-Webhook-Signature', '')
    ts  = int(request.headers.get('X-TF-Webhook-Timestamp', '0'))
    if abs(time.time() - ts) > 300:
        return jsonify(ok=False), 401
    key = hashlib.sha256(YOUR_SECRET.encode()).digest()
    expected = 'sha256=' + hmac.new(key, request.get_data(),
                                     hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        return jsonify(ok=False), 401
    payload = json.loads(request.get_data())
    # Tua logica: payload['event'], payload['payload']
    return jsonify(ok=True)

Scarica bundle completo (ZIP con README)

Validatore firma (debug)

Incolla i 3 valori dal tuo log per verificare se la firma è corretta. Calcolo HMAC eseguito 100% nel browser (Web Crypto API), il secret non viene mai inviato al server.

Eventi supportati (whitelist customer)

Evento	Quando
`dip.export`	Esibizione DIP costruita e pronta
`dip.cleanup`	ZIP DIP scaduto rimosso (TTL)
`dip.admin_download`	Admin ha scaricato la DIP per audit
`esibizione.notified`	Email inviata al richiedente
`esibizione.delivered`	Esibizione consegnata (download completato)
`esibizione.suspicious`	Pattern sospetto rilevato
`esibizione.force_retry`	Admin ha forzato retry su esibizione
`lotto.build`	Nuovo pacchetto AIP costruito
`lotto.xsd_drift_detected`	Drift schema XSD rilevato (regression)
`lotto.xsd_auto_validated`	Pacchetto auto-validato in fase di build

Retry policy

Se il tuo endpoint risponde non-2xx o va in timeout, il sistema riprova con backoff esponenziale:

1°

immediato

2°

+60s

3°

+5m

4°

+30m

5°

+2h

dead

+12h

Limite: max 5 webhook attivi per azienda. Dopo 5 fail consecutivi una delivery va in stato dead ma la subscription resta attiva.

Conservazione Digitale

Come funziona la conservazione

Webhook notifiche real-time

Cronologia notifiche