Webhook
Ricevi un evento per ogni ricevuta SDI e verifica la firma Getbeel-Signature.
Invece di interrogare l'API, registra un endpoint HTTPS: Getbeel gli invia un POST JSON firmato per ogni evento che scegli, sulle tue fatture, riconciliazioni e tasse.
| Parte | Regola |
|---|---|
| Richiesta | POST, corpo JSON, header Content-Type: application/json, User-Agent: getbeel-webhooks/1.0 e Getbeel-Signature |
| La tua risposta | Un 2xx qualsiasi entro 10 secondi. I redirect non vengono seguiti: un 3xx conta come errore |
| Nuovi tentativi | Dopo un non-2xx, un timeout o un errore di rete: di nuovo dopo 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h e 24 h. Fino a 9 tentativi in circa 3 giorni, poi l'invio è failed |
| Duplicati | L'invio è almeno una volta: deduplica sull'id dell'evento |
| Ordine | Non garantito: rileggi la fattura quando l'ordine conta |
| Modalità | Un endpoint test riceve gli eventi delle chiavi di test (la sandbox); un endpoint live quelli reali |
Aggiungere un endpoint
Nell'app apri Impostazioni → Chiavi API e MCP → Webhook, scegli Aggiungi endpoint, poi l'URL, la modalità e gli eventi. Il segreto di firma si vede una volta sola: conservalo sul tuo server.
- L'URL deve essere
httpssu un host pubblico. Host privati e interni sono rifiutati, anche quando un nome pubblico punta a uno di essi. - Invia evento di prova manda subito un evento di prova all'endpoint. Ogni invio è in Invii recenti, con lo stato, e Reinvia lo manda di nuovo.
- Un endpoint funziona finché il membro che l'ha aggiunto può gestire le impostazioni del team. Se perde quel permesso, gli invii si fermano.
Eventi
| Evento | Quando | Stato della fattura |
|---|---|---|
invoice.sent | Trasmessa allo SDI, in attesa dell'esito | sent |
invoice.delivered | Ricevuta di consegna (RC) | delivered |
invoice.not_delivered | Mancata consegna (MC) | not_delivered |
invoice.rejected | Notifica di scarto (NS), con i codici SDI | rejected |
Con una chiave di test gli eventi arrivano dalla sandbox, quindi puoi collaudare ogni caso.
Gli eventi su banca e documenti raccolti riguardano dati reali, quindi li ricevono solo gli endpoint live:
| Evento | Quando | data.object |
|---|---|---|
bank_statement.parsed | Un estratto conto è stato letto | bank_statement |
reconciliation.completed | L'abbinamento AI è terminato: gli abbinamenti si possono verificare | reconciliation |
received_invoice.created | È arrivata una fattura fornitore dallo SDI (source: "sdi") o è stata raccolta (scansione della casella, inoltro o caricamento) | received_invoice |
invoice.emailed | È stata inviata al cliente un email con la fattura o un sollecito | invoice_email |
invoice.email_failed | L'email al cliente non è partita (error dice perché) | invoice_email |
invoice.paid | I pagamenti registrati coprono l'importo dovuto | invoice |
invoice.overdue | Il giorno dopo la scadenza, una volta, se la fattura non è pagata | invoice |
filing.ready | È stato preparato (o ricalcolato) un adempimento | filing |
filing.filed | È stata caricata la quietanza: l'adempimento è pagato | filing |
filing.needs_review | Un adempimento preparato aspetta la revisione del commercialista | filing |
filing.changes_requested | Il commercialista l'ha rimandato indietro con un commento | filing |
filing.approved | Approvato: si può pagare o inviare | filing |
filing.skipped | Segnato da non fare, con il motivo | filing |
filing.approval_due | Con l'approvazione del commercialista obbligatoria, scade entro 5 giorni lavorativi e non è ancora approvato (una volta per scadenza) | filing |
tax_deadline.upcoming | Una scadenza fiscale è tra 7 giorni o domani e non è pagata | tax_deadline |
tax_deadline.insufficient_funds | Un F24 in scadenza entro 5 giorni lavorativi supera il saldo di ogni conto bancario collegato | f24_funds_alert |
bank_connection.expiring | Il consenso di una banca collegata scade entro 7 giorni | bank_connection |
bank_connection.expired | Il consenso è scaduto o revocato: gli aggiornamenti sono fermi finché non ricolleghi | bank_connection |
In arrivo
invoice.accepted e invoice.refused (esito della PA),
invoice.terms_expired (decorrenza termini).
Il payload
Ogni evento è un oggetto event; per gli eventi delle fatture data.object è la fattura completa, la stessa di GET /invoices/{id} (senza le righe).
{
"id": "evt_8a1f…",
"object": "event",
"type": "invoice.rejected",
"created": 1761742800,
"livemode": true,
"data": {
"object": {
"object": "invoice",
"id": "fe_3f1c…",
"number": "121",
"status": "rejected",
"sdi": {
"identificativo_sdi": "7731024559",
"file_name": "IT13815270965_0004N.xml",
"error_message": "00305 1.4.1.1.2 <IdCodice> non valido",
"error_codes": ["00305"],
"errors": [
{ "code": "00305", "description": "1.4.1.1.2 <IdCodice> non valido" }
],
"available_since": null,
"updated_at": "2026-10-30T15:02:11.000Z"
},
"…": "…"
}
}
}Usa type per decidere cosa fare. Un evento può arrivare più di una volta o in ritardo: deduplica su id e, se ti serve lo stato attuale, rileggi la fattura con GET /invoices/{id}. Cosa significa ogni stato: ciclo di vita SDI.
Verificare la firma
Ogni richiesta ha un header Getbeel-Signature:
Getbeel-Signature: t=1761742800,v1=5f2b9c…tè il timestamp Unix (secondi) dell'invio.v1è l'HMAC-SHA256, in esadecimale, della stringat+.+ corpo grezzo della richiesta, calcolato con il segreto del tuo endpoint.
Per verificarla: ricalcola l'HMAC sul corpo grezzo (prima di fare il parsing del JSON), confrontalo in tempo costante con v1 e rifiuta i timestamp troppo vecchi (consigliamo 5 minuti) per evitare replay.
import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';
export function verifyGetbeelSignature(
rawBody,
header,
secret,
toleranceSeconds = 300,
) {
let timestamp;
const signatures = [];
for (const part of (header ?? '').split(',')) {
const [key, value] = part.trim().split('=');
if (key === 't') timestamp = value;
if (key === 'v1' && value) signatures.push(value);
}
if (!timestamp || signatures.length === 0) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds)
return false;
const expected = createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
return signatures.some(
(signature) =>
signature.length === expected.length &&
timingSafeEqual(Buffer.from(signature), Buffer.from(expected)),
);
}
const app = express();
// Express: leggi il corpo grezzo, non il JSON già interpretato
app.post(
'/webhooks/getbeel',
express.raw({ type: 'application/json' }),
(req, res) => {
const ok = verifyGetbeelSignature(
req.body.toString('utf8'),
req.get('Getbeel-Signature'),
process.env.GETBEEL_WEBHOOK_SECRET,
);
if (!ok) return res.sendStatus(400);
const event = JSON.parse(req.body);
// gestisci event.type …
res.sendStatus(200);
},
);Se qualcosa non va
Cosa mostra Invii recenti, e cosa fare:
| Errore di invio | Causa | Soluzione |
|---|---|---|
HTTP 4xx o 5xx | Il tuo endpoint ha risposto con un errore | Correggi il gestore; Getbeel riprova secondo lo schema sopra |
Timed out after 10 seconds | Nessuna risposta in 10 secondi | Rispondi subito 2xx, poi fai il lavoro in una coda |
Could not connect to the endpoint | Errore DNS, TLS o di rete | Controlla che l'URL sia raggiungibile da internet |
Endpoint URL not allowed | Non è https, o è un host privato | Usa un URL https pubblico (per le prove va bene webhook.site) |
The member who added this endpoint can no longer manage webhooks | Quel membro è uscito o ha perso il permesso | Aggiungi di nuovo l'endpoint come membro che gestisce le impostazioni |
Gli errori che non possono risolversi da soli (URL non ammesso, endpoint disattivato, permesso del membro) non vengono ritentati.
Buone pratiche
- Rispondi subito con un
2xxe fai il lavoro pesante dopo, in una coda. - Lo stesso evento può arrivare più di una volta: rendi la gestione idempotente (per esempio non inviare due volte la stessa email al cliente).
- Gli eventi possono arrivare in ordine diverso da quello in cui sono avvenuti: se l'ordine conta, rileggi lo stato con
GET /invoices/{id}. - Tieni il segreto del webhook sul server, come la chiave API.
I webhook sono appena usciti. Eventi, header e algoritmo di firma sono quelli
indicati qui; i campi di data sono descritti nel riferimento API e possono
crescere con nuovi campi.