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

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.

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