# Webhook (https://docs.getbeel.com/it/api/webhooks)

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`](#verificare-la-firma)                                    |
| 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 [#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 [#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](/it/api/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](/it/api/bank-reconciliation) è 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](/it/api/filings)                                                                   | `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](/it/api/taxes) è 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](/it/api/bank-connections) scade entro 7 giorni                                                   | `bank_connection`  |
| `bank_connection.expired`         | Il consenso è scaduto o revocato: gli aggiornamenti sono fermi finché non ricolleghi                                                  | `bank_connection`  |

<Callout title="In arrivo">
  `invoice.accepted` e `invoice.refused` (esito della PA),
  `invoice.terms_expired` (decorrenza termini).
</Callout>

## Il payload [#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).

```json title="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](/it/api/sdi-lifecycle).

## Verificare la firma [#verificare-la-firma]

Ogni richiesta ha un header `Getbeel-Signature`:

```text
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.

<Tabs items={['Node.js', 'Python']}>
<Tab value="Node.js">

```js
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);
  },
);
```

</Tab>
<Tab value="Python">

```python
import hashlib
import hmac
import os
import time

from flask import Flask, request

app = Flask(__name__)


def verify_getbeel_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    timestamp, signatures = None, []

    for part in (header or "").split(","):
        key, _, value = part.strip().partition("=")
        if key == "t":
            timestamp = value
        elif key == "v1" and value:
            signatures.append(value)

    if not timestamp or not timestamp.isdigit() or not signatures:
        return False
    if abs(time.time() - int(timestamp)) > tolerance:
        return False

    expected = hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()

    return any(hmac.compare_digest(expected, signature) for signature in signatures)


# Flask: request.get_data() restituisce il corpo grezzo
@app.post("/webhooks/getbeel")
def getbeel_webhook():
    if not verify_getbeel_signature(
        request.get_data(), request.headers.get("Getbeel-Signature"), os.environ["GETBEEL_WEBHOOK_SECRET"]
    ):
        return "", 400

    event = request.get_json()
    # gestisci event["type"] …
    return "", 200
```

</Tab>
</Tabs>

## Se qualcosa non va [#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 [#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.

<Callout type="info">
  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.
</Callout>
