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 valueauthentication_token
in the ApiConfiguration entity.
Examples
- In case you chose
header
asauthentication_type
,Bearer
asauthentication_key
andmysecret
asauthentication_token
, A-Cube will send the token in the headerAuthorization: Bearer mysecret
. - While in case you chose
query
asauthentication_type
,token
asauthentication_key
andmysecret
asauthentication_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 |
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 invoicecustomer-invoice
: the payload is theInvoice
JSON resource as described in the APIcustomer-notification
: see Receiving a notification for a sent invoiceinvoice-status-quarantena
: see Notifications for changes in invoices markinginvoice-status-invoice-error
: see Notifications for changes in invoices markinglegal-storage-missing-vat
: the payload is theBusinessRegistryConfiguration
JSON resource as described in the APIlegal-storage-receipt
: the payload is thePreservedDocument
JSON resource as described in the APIreceipt
: the payload is theReceipt
JSON resource as described herereceipt-retry
: see herereceipt-error
: see hereappointee
: see here