Configure the webhook communication method

Use the Indirect Tax API to configure the webhook (Svix) communication method and events.

Configure an ERP system

This configuration is valid for all organizations you manage. To configure this communication method for a single organization, you must use the Compliance Network website.

Note:

Only partners and Sovos Professional Services can use the API to configure the communication method.

Send a POST request to /v2/configurations/workspaces/settings.
Include the following headers in your request:
- Content-Type: application/json
- Authorization: Bearer {accessToken}
- x-correlationId: {uniqueValue}

Include the following parameters inside the JSON payload in the request body.


Name						Type	Required	Description
context						string	Yes	Use "notification".
configurations						array of objects	Yes
	name					string	Yes	Use "communication_method".
	value					object	Yes
		type				string	Yes	Use "pushingV2" (Svix).
		autoAcknowledgement				boolean	No	Sovos recommends using "true" to automatically mark all received notifications as read. Default: "false".
		appResponseAsLink				boolean	No	Use "true" to turn the application response into a download link or "false" to access your application response as Base64-encoded binary data. Sovos recommends using "true" and configuring each attachment's `isBase64` as "true", so you get a direct download link in the payload but you can access each attachment as binary data. Default value: "false".
	scope					object	Yes
		systemId				string	Yes	Unique identifier for the ERP system.
	name					string	Yes	Use "events".
		value				object	Yes
			items			array of objects	Yes
				statusEvent		string	Yes	Use an event name. For the complete list, see SCI cloud status code
				attachments		array of objects	Yes
					attachmentType	string	No	Use a value such as "Legal" or "LegalResponse".
					isBase64	boolean	No	Use "true" to access your attachment as binary data and "false" to turn the attachment into a download link. Sovos recommends using "true" and configuring `appResponseAsLink` as "true", so you get a direct download link in the payload but you can access each attachment as binary data.
	scope					object	Yes
		systemId				string	Yes	Unique identifier for the ERP system

Upon successful configuration, the API returns a JSON object. Make sure you store your "appId", which you need to make other API requests. The next step is retrieving your Consumer App Portal link.

Samples for configuring the webhook communication method

Request sample

curl --location --request POST 'https://api-test.sovos.com/v2/configurations/workspaces/settings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {accessToken}' \
--header 'x-correlationId: {uniqueValue}' \
--data '[
	{
		"context": "notification",
		"configurations": [
			{
				"name": "communication_method",
				"value": {
					"type": "pushingV2",
					"autoAcknowledgement": true,
					"appResponseAsLink": true
				},
				"scope": {
					"systemId": "TestSystemId"
				}
			},
			{
				"name": "events",
				"value": {
					"items": [
						{
							"statusEvent": "workflow.completed",
							"attachments": [
								{
									"attachmentType": "Legal",
									"isBase64": true
								},
								{
									"attachmentType": "LegalResponse",
									"isBase64": true
								}
							]
						},
						{
							"statusEvent": "system.error",
							"attachments": []
						}
					]
				},
				"scope": {
					"systemId": "TestSystemId"
				}
			}
		]
	}
]'

Response sample

{
 "status": 201,
 "message": "Created",
 "success": true,
 "timestamp": 1771588256125,
 "data": [
  {
   "message": "Configurations are created",
   "statusCode": 201,
   "configurationContextResponse": {
    "context": "Webhook",
    "configurations": [
     {
      "id": "c0251dfe-42f6-4637-9232-a310880f370a",
      "name": "communication_method",
      "value": {
       "type": "pushingV2",
       "autoAcknowledgement": true,
       "appResponseAsLink": true
      },
      "scope": {
       "systemId": "TestERPSystemId",
       "workspaceId": "7a8d4ea5-d977-483d-ab85-1c308d5c03e0"
      },
      "auditData": {
       "createdAt": 1771588255,
       "createdBy": "user@company.com",
       "isDeleted": false,
       "version": 1
      }
     }
    ]
   }
  },
  {
   "message": "Configurations are created",
   "statusCode": 201,
   "configurationContextResponse": {
    "context": "Webhook",
    "configurations": [
     {
      "id": "179a1484-ff58-4373-971c-c98aafca8242",
      "name": "bearer_auth_configuration",
      "value": {
       "appId": "app_39vtDukPH25wt0DQ2YLXH3dyeNr"
      },
      "scope": {
       "systemId": "TestERPSystemId",
       "workspaceId": "7a8d4ea5-d977-483d-ab85-1c308d5c03e0"
      },
      "auditData": {
       "createdAt": 1771588255,
       "createdBy": "user@company.com",
       "isDeleted": false,
       "version": 1
      }
     }
    ]
   }
  },
  {
   "message": "Configurations are created",
   "statusCode": 201,
   "configurationContextResponse": {
    "context": "Notification",
    "configurations": [
     {
      "id": "e42c261e-f997-4bd7-ad3c-45407562a455",
      "name": "communication_method",
      "value": {
       "type": "pushingV2",
       "autoAcknowledgement": true,
       "appResponseAsLink": true
      },
      "scope": {
       "systemId": "TestERPSystemId",
       "workspaceId": "7a8d4ea5-d977-483d-ab85-1c308d5c03e0"
      },
      "auditData": {
       "createdAt": 1771588255,
       "createdBy": "user@company.com",
       "isDeleted": false,
       "version": 1
      }
     },
     {
      "id": "bbe2bda6-1147-4150-925d-753aef9ce6ea",
      "name": "events",
      "value": {
       "items": [
        {
         "statusEvent": "document.completed",
         "attachments": [
          {
           "attachmentType": "Legal",
           "isBase64": false
          },
          {
           "attachmentType": "LegalResponse",
           "isBase64": false
          }
         ]
        },
        {
         "statusEvent": "system.error",
         "attachments": []
        }
       ]
      },
      "scope": {
       "systemId": "TestERPSystemId",
       "workspaceId": "7a8d4ea5-d977-483d-ab85-1c308d5c03e0"
      },
      "auditData": {
       "createdAt": 1771588255,
       "createdBy": "user@company.com",
       "isDeleted": false,
       "version": 1
      }
     }
    ]
   }
  }
 ]
}

Sovos Docs

Configure the webhook communication method

Samples for configuring the webhook communication method

Request sample

Response sample

sovos-footer