GetbeelDocs

Webhooks

Get an event for every SDI receipt and verify the Getbeel-Signature header.

Instead of polling, register an HTTPS endpoint: Getbeel sends it a signed JSON POST for every event you choose, about your invoices, reconciliations and taxes.

PartRule
RequestPOST, JSON body, headers Content-Type: application/json, User-Agent: getbeel-webhooks/1.0 and Getbeel-Signature
Your answerAny 2xx within 10 seconds. Redirects are not followed: a 3xx counts as a failure
RetriesAfter a non-2xx, a timeout or a network error: again after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h and 24 h. Up to 9 attempts over about 3 days, then the delivery is failed
DuplicatesDelivery is at least once: deduplicate on the event id
OrderNot guaranteed: re-read the invoice when order matters
ModesA test endpoint gets the events of test keys (the sandbox); a live endpoint gets real ones

Add an endpoint

In the app, open Settings → API keys & MCP → Webhooks, choose Add endpoint, then the URL, the mode and the events. The signing secret is shown once: store it on your server.

  • The URL must be https on a public host. Private and internal hosts are refused, also when a public name resolves to one.
  • Send test event posts a test event to the endpoint at once. Every delivery is listed under Recent deliveries, with the status, and Redeliver sends one again.
  • An endpoint works while the member who added it can manage the team's settings. When they lose that permission, its deliveries stop.

Events

EventWhenInvoice status
invoice.sentTransmitted to SDI, waiting for the outcomesent
invoice.deliveredDelivery receipt (RC)delivered
invoice.not_deliveredDelivery failure (MC)not_delivered
invoice.rejectedRejection notice (NS), with the SDI codesrejected

With a test key the events come from the sandbox, so you can test every case.

Bank and collection events carry real data, so only live endpoints receive them:

EventWhendata.object
bank_statement.parsedA bank statement was readbank_statement
reconciliation.completedAI matching finished: the matches can be reviewedreconciliation
received_invoice.createdA supplier invoice arrived from SDI (source: "sdi") or was collected (mailbox scan, forwarding or upload)received_invoice
invoice.emailedAn invoice or reminder email was sent to the customerinvoice_email
invoice.email_failedThe customer email could not be sent (error says why)invoice_email
invoice.paidThe payments recorded cover the amount dueinvoice
invoice.overdueThe day after the due date, once, when the invoice is unpaidinvoice
filing.readyA filing was prepared (or recomputed)filing
filing.filedIts receipt was uploaded (paid), or a return was marked filed with its protocol numberfiling
filing.needs_reviewA prepared filing waits for the commercialista's reviewfiling
filing.changes_requestedThe commercialista sent it back with a commentfiling
filing.approvedApproved (visto bueno): it can be paid or filedfiling
filing.skippedMarked not to be done, with the reasonfiling
filing.approval_dueWith the commercialista's approval required, due within 5 working days and still not approved (once per due date)filing
tax_deadline.upcomingA tax deadline is 7 days or 1 day away, not paidtax_deadline
tax_deadline.insufficient_fundsAn F24 due within 5 working days is higher than the balance of every connected bank accountf24_funds_alert
bank_connection.expiringA connected bank's consent ends within 7 daysbank_connection
bank_connection.expiredThe consent ended or was revoked: updates stop until you reconnectbank_connection

Coming soon

invoice.accepted and invoice.refused (public administration outcome), invoice.terms_expired (decorrenza termini).

The payload

Every event is an event object; for invoice events data.object is the full invoice, the same as GET /invoices/{id} (without the lines).

POST to your 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"
      },
      "…": "…"
    }
  }
}

Branch on type. An event can arrive more than once or late: deduplicate on id and, when you need the current state, read the invoice with GET /invoices/{id}. What each status means: SDI lifecycle.

Verifying the signature

Every request has a Getbeel-Signature header:

Getbeel-Signature: t=1761742800,v1=5f2b9c…
  • t is the Unix timestamp (seconds) of the delivery.
  • v1 is the hex HMAC-SHA256 of the string t + . + the raw request body, computed with your endpoint's secret.

To verify it: recompute the HMAC over the raw body (before parsing the JSON), compare it with v1 in constant time, and reject old timestamps (we suggest 5 minutes) to prevent replays.

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: read the raw body, not the parsed JSON
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);
    // handle event.type …
    res.sendStatus(200);
  },
);

If it fails

What Recent deliveries shows, and what to do:

Delivery errorCauseFix
HTTP 4xx or 5xxYour endpoint answered an errorFix the handler; Getbeel retries on the schedule above
Timed out after 10 secondsNo answer in 10 secondsAnswer 2xx first, then do the work in a queue
Could not connect to the endpointDNS, TLS or network errorCheck that the URL is reachable from the internet
Endpoint URL not allowedNot https, or a private hostUse a public https URL (for tests, webhook.site works)
The member who added this endpoint can no longer manage webhooksThat member left or lost the permissionAdd the endpoint again as a member who manages settings

Failures that cannot succeed (URL not allowed, endpoint disabled, the member's permission) are not retried.

Good practice

  • Answer with a 2xx right away and do heavy work later, in a queue.
  • The same event can arrive more than once: make handling idempotent (for example, don't email the customer twice).
  • Events can arrive out of order: if order matters, re-read the status with GET /invoices/{id}.
  • Keep the webhook secret on your server, like the API key.

Webhooks have just shipped. Events, header and signature algorithm are as described here; the fields of data are described in the API reference and may gain new fields.

On this page