Skip to main content
Download OpenAPI

Transfer webhooks

Transfer can notify your application when a document is accepted by A-Cube's invoicing service or when processing fails. A-Cube configures the success and failure callbacks during onboarding.

Confirm your setup

Ask A-Cube to confirm webhook availability for your destination, input format and upload channel. The examples below cover Italy and Peppol success callbacks, Italy validation failures and file processing failures. They are not a common webhook contract for every destination or every error. For complete API examples, follow UBL JSON to KSeF or CSV to SdI.

Configure the callbacks​

Provide A-Cube with:

  • Your destination and environment, sandbox or production.
  • The URLs that should receive successful results and failures. They can be the same URL.
  • The input format and upload channel you will use.
  • Your correlation requirements, so you can match each callback to the original invoice.

A-Cube confirms the payload and endpoint authentication for your setup. Callback URLs are configured on your account; they are not fields of the upload request.

Before replacing polling, test both a successful invoice and a failing file in sandbox. Confirm the returned correlation value, coverage of conversion errors and validation errors, and delivery and retry behavior with A-Cube.

Success​

A success callback means the document was accepted by A-Cube's invoicing service. It does not confirm acceptance by SdI or delivery on Peppol. Continue tracking the returned UUID in that service.

For Italy:

{
  "e2e_id": "<correlation-id>",
  "gov_it_uuid": "<invoice-uuid>"
}

Use gov_it_uuid to check the SdI outcome.

For Peppol:

{
  "e2e_id": "<correlation-id>",
  "peppol_uuid": "<document-uuid>"
}

Use peppol_uuid to follow the document on the network.

Failure​

An invoice validation failure includes a message and the invoicing service's validation response. For a response containing a list of violations:

{
  "e2e_id": "<correlation-id>",
  "error_message": "Found violations invoice validation, for more information check the violations field",
  "violations": [
    {
      "propertyPath": "<affected-field>",
      "message": "<validation-message>"
    }
  ]
}

The violations value is passed through from the invoicing service. It can be a list as above, or a validation response object containing its own violations list. Confirm the shape for your flow during onboarding.

A failure earlier in file processing can contain only e2e_id and error_message. Depending on the failure, error_message can be a string or a list of message objects. Do not require violations on every failure callback.

For full error details, read the upload's documents with the tracking API. Include errors on the input file, not only invoices sent to the destination. See Violation codes for corrections.

Correlation and recovery​

e2e_id is the callback's correlation value. Confirm its value with A-Cube for your flow: do not assume it is the upload id or the End-to-end ID you sent in a REST request. For the Peppol-to-SdI flow, it is derived from invoice data.

Store the callback and its destination UUID before performing further processing. Handle repeated callbacks without sending the invoice again. If an expected callback is missing, check the upload through the tracking API; the absence of a callback does not mean the upload failed.

Tax authority and network webhooks​

The destination's invoicing service has separate notifications for the outcome after Transfer. See the webhooks of each destination:

Configure these separately if your integration needs them. You can also follow the destination outcome through its API, as shown in UBL JSON to KSeF and CSV to SdI.

Last updated on