AvaTax App Architecture
Webhook events​
The AvaTax App uses the following webhook events for tax reporting and calculations:
Calculating taxes​
Calculating taxes using external tax providers happens through a synchronous CalculateTaxes webhook event. A synchronous webhook awaits a response from the app before continuing.
While the app is waiting for the values of the calculated taxes, the sequence of actions is as follows:
sequenceDiagram
CalculateTaxes->>+App: Send webhook payload
App-->>-AppMetadata: Fetch app configuration from metadata
AppMetadata-->>+App: Return configuration
App-->>+TaxProvider: Use configuration & webhook payload to create transaction
TaxProvider-->>-App: Return created transaction
App-->>-CalculateTaxes: Transform the transaction and return as webhook responseDuring tax calculation, the transactions on the AvaTax side are not recorded. They will not appear in the tax provider's dashboard.
Recording transactions​
Once the order is finalized, we want to send a transaction to the tax provider for tax reporting. This is done through asynchronous webhook events that fire on different order lifecycle actions.
sequenceDiagram
OrderConfirmed->>+App: Send webhook payload
App-->>-AppMetadata: Fetch app configuration from metadata
AppMetadata-->>+App: Return configuration
App-->>+TaxProvider: Use configuration & webhook payload to create transaction
TaxProvider-->>-App: Return created transactionCommitting transactions will happen during the transaction creation based on the provider configuration.
For example, the transaction is committed on OrderConfirmed if the isAutocommit flag is set to true in the configuration.
Canceling transactions​
sequenceDiagram
OrderCancelled->>+App: Send webhook payload
App-->>-AppMetadata: Fetch app configuration & transaction id from metadata
AppMetadata-->>+App: Return configuration & transaction id
App-->>+TaxProvider: Use configuration & webhook payload to cancel/void transaction
TaxProvider-->>-App: Return