Webhooks

You can configure your own webhooks that A-CUBE API will call when an event happens. To manage your endpoints you can use the API or the dashboard.

Security

To ensure that the transmission of the information to your public endpoints comes from A-Cube, you can:

Configure a secret token

Configure a secret token in the ApiConfiguration entity that A-Cube will send along with the request to your webhook endpoint.

• Choose authentication_type = query to ask A-Cube to send the token as a query parameter.
• Choose authentication_type = header to ask A-Cube to send the token as a header.
• Configure the token key authentication_key and the token value authentication_token in the ApiConfiguration entity.

Examples

• In case you chose header as authentication_type, Bearer as authentication_key and mysecret as authentication_token, A-Cube will send the token in the header Authorization: Bearer mysecret.
• While in case you chose query as authentication_type, token as authentication_key and mysecret as authentication_token, A-Cube will send the token in the query parameter ?token=mysecret.

Verify the signature

Verify the signature that A-Cube sends along with the request to your webhook as explained here.

Events

Event	When it happens
supplier-invoice	an invoice is received from SDI
customer-invoice	an invoice is sent successfully to SDI
customer-notification	a notification for a sent invoice comes from SDI
invoice-status-quarantena	the invoice marking changes from waiting to quarantena
invoice-status-invoice-error	the invoice marking changes from quarantena to invoice-error
legal-storage-missing-vat	a BusinessRegistryConfiguration is missing the email address required to activate the Legal Storage
legal-storage-receipt	a PreservedDocument receives the receipt from the legal storage
receipt	a new receipt is submitted and ready to download
receipt-retry	failed to submit a receipt because the communication with the Tax Authority portal failed and submission will be retried
receipt-error	failed to submit a receipt for an error signaled by Tax Authority portal
appointee	the process of adding an appointee for smart receipts succeeded
sistemats-receipt-ready	a sistemats expense receipt is ready
job	a job succesfully completed
job-error	a job completed with error

All the messages sent to your endpoint are sent with a POST request. We manage sending the messages to your endpoints with a queue: if your endpoint fails (we don't get a 200 response) then the webhook will retry 15 times every 300 seconds with a back-off rate of 1.25 for a total of about 10 hours.

If you want to disable endpoints during an operation you can send header X-DisableEndpoints: true. This header takes effect when sending a new customer invoice or when importing customer or supplier invoices.

Retrigger webhooks

If your endpoint missed a webhook or you need to receive it again, you can manually retrigger the webhook notification using the following endpoints:

• Notify invoice — retriggers the webhook for an invoice (POST /invoices/{id}/notify)
• Notify invoice notifications — retriggers the webhook for an invoice's notifications (POST /invoices/{id}/notifications/notify)

Payloads

• supplier-invoice: see Receiving an invoice
• customer-invoice: the payload is the Invoice JSON resource as described in the API
• customer-notification: see Receiving a notification for a sent invoice
• invoice-status-quarantena: see Notifications for changes in invoices marking
• invoice-status-invoice-error: see Notifications for changes in invoices marking
• legal-storage-missing-vat: the payload is the BusinessRegistryConfiguration JSON resource as described in the API
• legal-storage-receipt: the payload is the PreservedDocument JSON resource as described in the API
• receipt: the payload is the Receipt JSON resource as described here
• receipt-retry: see here
• receipt-error: see here
• appointee: see here
• sistemats-receipt-ready: see here
• job: see here
• job-error: see here

Completed Job Payload

{
  "uuid": "019c2d2b-c36d-7bde-a46e-1aefad251c22",
  "type": "invoice-download",
  "status": "completed",
  "parameters": {
    "daily": true
  },
  "fiscal_id": "12345678910",
  "downloadable": false,
  "scheduled_at": "2026-02-05 09:39:00",
  "started_at": "2026-02-05 09:39:40",
  "completed_at": "2026-02-05 09:39:40",
  "output": null,
  "created_at": "2026-02-05 09:39:28"
}

Failed Job Payload

{
  "uuid": "019c2d2b-c36d-7bde-a46e-1aefad251c22",
  "type": "invoice-download",
  "status": "error",
  "parameters": {
    "daily": true
  },
  "fiscal_id": "12345678910",
  "downloadable": false,
  "scheduled_at": "2026-02-05 09:39:00",
  "started_at": "2026-02-05 09:39:40",
  "completed_at": "2026-02-05 09:39:40",
  "output": "Generic Error",
  "created_at": "2026-02-05 09:39:28"
}