GetbeelDocs

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.

ParteRegola
RichiestaPOST, corpo JSON, header Content-Type: application/json, User-Agent: getbeel-webhooks/1.0 e Getbeel-Signature
La tua rispostaUn 2xx qualsiasi entro 10 secondi. I redirect non vengono seguiti: un 3xx conta come errore
Nuovi tentativiDopo 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
DuplicatiL'invio è almeno una volta: deduplica sull'id dell'evento
OrdineNon 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 https su 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

EventoQuandoStato della fattura
invoice.sentTrasmessa allo SDI, in attesa dell'esitosent
invoice.deliveredRicevuta di consegna (RC)delivered
invoice.not_deliveredMancata consegna (MC)not_delivered
invoice.rejectedNotifica di scarto (NS), con i codici SDIrejected

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:

EventoQuandodata.object
bank_statement.parsedUn estratto conto è stato lettobank_statement
reconciliation.completedL'abbinamento AI è terminato: gli abbinamenti si possono verificarereconciliation
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 sollecitoinvoice_email
invoice.email_failedL'email al cliente non è partita (error dice perché)invoice_email
invoice.paidI pagamenti registrati coprono l'importo dovutoinvoice
invoice.overdueIl giorno dopo la scadenza, una volta, se la fattura non è pagatainvoice
filing.readyÈ stato preparato (o ricalcolato) un adempimentofiling
filing.filedÈ stata caricata la quietanza: l'adempimento è pagatofiling
filing.needs_reviewUn adempimento preparato aspetta la revisione del commercialistafiling
filing.changes_requestedIl commercialista l'ha rimandato indietro con un commentofiling
filing.approvedApprovato: si può pagare o inviarefiling
filing.skippedSegnato da non fare, con il motivofiling
filing.approval_dueCon l'approvazione del commercialista obbligatoria, scade entro 5 giorni lavorativi e non è ancora approvato (una volta per scadenza)filing
tax_deadline.upcomingUna scadenza fiscale è tra 7 giorni o domani e non è pagatatax_deadline
tax_deadline.insufficient_fundsUn F24 in scadenza entro 5 giorni lavorativi supera il saldo di ogni conto bancario collegatof24_funds_alert
bank_connection.expiringIl consenso di una banca collegata scade entro 7 giornibank_connection
bank_connection.expiredIl consenso è scaduto o revocato: gli aggiornamenti sono fermi finché non ricolleghibank_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).

POST al tuo endpoint
{
  "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 stringa t + . + 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 invioCausaSoluzione
HTTP 4xx o 5xxIl tuo endpoint ha risposto con un erroreCorreggi il gestore; Getbeel riprova secondo lo schema sopra
Timed out after 10 secondsNessuna risposta in 10 secondiRispondi subito 2xx, poi fai il lavoro in una coda
Could not connect to the endpointErrore DNS, TLS o di reteControlla che l'URL sia raggiungibile da internet
Endpoint URL not allowedNon è https, o è un host privatoUsa un URL https pubblico (per le prove va bene webhook.site)
The member who added this endpoint can no longer manage webhooksQuel membro è uscito o ha perso il permessoAggiungi 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 2xx e 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.

In questa pagina