Visma.net ERP API Webhooks Setup API & ERP UI (Event - Subscription - Notification)

[#1]

Available Events

The endpoint /event can be used to show a list of the different Webhook-events you can subscribe to. The call is of type GET and takes no parameters.

[
    {
        "eventType": "supplier_changed",
        "name": "Supplier changed",
        "description": "Triggered after creation or update of a Supplier"
    },
    {
        "eventType": "inventoryitem_changed",
        "name": "Inventory Item changed",
        "description": "Triggered after creation or update of an InventoryItem"
    },...
]

Event subscriptions

You use event subscriptions to register your application to receive webhook-events from Visma.net.
Subscriptions are managed through the /subscription endpoint in the API.

 

 

 

Register a new subscription

You register a new subscription with the POST-method on the /subscription endpoint. 

To register a subscription you need to provide two values in the data-body of the POST-call:
event: This is the type of event you want to subscribe to. You get this value from eventType-field in the GET Events call.
hookUri: The Uri where you would like to receive the webhook-message.

{
  "event": "customer_changed",
  "hookUri": "https://webhook.site/2f249a6c-132e-4812-8093-5ddbc043433e"
}

If successful, the call will return HTTP-code 201 with the following data-body:

{
    "id": 660,
    "event": "customer_changed",
    "hookUri": "https://webhook.site/2f249a6c-132e-4812-8093-5ddbc043433e"
}

Notice the field id, this is the unique identification of this subscription, and you will use this to modify or delete the subscription later.

Rules 

• You can only subscribe to the same event once per user (token) per company (ipp-company-id). Attempts to register multiple subscriptions will result in HTTP 400:
  "There's already a subscription for this event"

List all subscriptions

You can list all the subscriptions for the current user (token) by calling the GET-method of the /subscriptions endpoint.

The call will return a list of all the current subscriptions including their id, eventtype and hookUri.

[
    {
        "id": 600,
        "event": "customer_changed",
        "hookUri": "https://webhook.site/3806cb96-f5b6-4135-a173-01b48351f0f7"
    },
    {
        "id": 660,
        "event": "inventoryitem_changed",
        "hookUri": "https://webhook.site/2f249a6c-132e-4812-8093-5ddbc043433e"
    }
]

Get details of single subscription

To get details of a single subscription you can provide the subscription-id to get GET-method of endpoint /subscription (/subscription/600).

The call will return the information about the requested subscription:

{
    "id": 600,
    "event": "customer_changed",
    "hookUri": "https://webhook.site/3806cb96-f5b6-4135-a173-01b48351f0f7"
}

Update a subscription

To update the details of a specific subscription you use the PUT-method of /subscription endpoint. You need to specify the subscription-id as part the url (/subscription/600).

The data-body must contain the changes you want to make. Only the hookUri-property can be changed, other changes will fail or be ignored.

{
    "hookUri": "https://webhook.site/3806cb96-f5b6-4135-a173-01b48351f0f7"
}

Rules

• The id of a subscription cannot be changed.
• The event of a subscription cannot be changed.

Delete a subscription

To delete an existing subscription you use the DELETE-method of the /subscription endpoint. You need to specify the subscription-id as part the url (/subscription/600).

Notifications

A notification is the actual webhook-message that is sent from Visma.net to the relevant subscriptions when an event occurs.

Characteristics

• For “register-entities” like customer or employee a notification is sent for all changes to the entity.
• For “transaction-entities” like sales_order or purchase_order a notification is sent only when the status of the entity changes.
• Notifications are sent only once. If the receiver (subscription webhookUri) is not available the notification is not automatically resent.
• Webhook-messages must be enabled on the entity for the notification to be sent (see section “Enable webhooks”)

The notification

The notifications will be sent to the registered webhookUri as a HTTP POST-call with the following JSON-body.

{
    "notificationId": "541830a1-1c0c-4a21-aaa5-28f3457f5771",
    "contextId": "123456",
    "event": "customer_changed",
    "resourceUri": "https://integration.visma.net/API/controller/api/v1/customer/10023",
    "action": "UPDATED",
    "timeStamp": 637109004130730000
  }

The body contains the following data-properties:

Name	Description
notificationId	A unique Id for this notfication
contextId	The id of the context (ipp-company-id) in Visma.net
event	The type of event that triggered the notification
resourceUri	The Uri to the specific entity that triggered the notification
action	The action that was done on the entity
timeStamp	The time the notification was sent (epoch)

Webhook notifications are in UTC date format. Clients can convert UTC into any desired local time. The reason is that webhook is not running in a "user context" - there is no data regarding which user triggered specific webhook, hence no data regarding user local settings.

Get notifications

A list of the previously sent notifications can be retrieved by calling the GET-method of the /notification endpoint. The request can be filtered by date and eventType.

[
    {
        "notificationId": "1aeb9da8-075e-4885-ae42-a99dd40e92f6",
        "contextId": "1113659",
        "event": "customer_changed",
        "resourceUri": "https://integration.visma.net/API/controller/api/v1/customer/10024",
        "action": "CREATED",
        "timeStamp": 637008739745700000
    },
    {
        "notificationId": "e2e2cd89-85bd-4522-b9c1-a930224c94e5",
        "contextId": "1113659",
        "event": "customer_changed",
        "resourceUri": "https://integration.visma.net/API/controller/api/v1/customer/10024",
        "action": "UPDATED",
        "timeStamp": 637008755442770000
    }
]

Get failed notifications

A list of notifications that has failed can be retrieved by calling the GET-method of the /notification/failed endpoint. This request can be filtered by date and eventtype.

[
    {
        "notificationId": "1aeb9da8-075e-4885-ae42-a99dd40e92f6",
        "contextId": "1113659",
        "event": "customer_changed",
        "resourceUri": "https://integration.visma.net/API/controller/api/v1/customer/10024",
        "action": "CREATED",
        "timeStamp": 637008739745700000
    }
]

Get single notification 

The notification-endpoint also provides a method for getting a single notification. The method requires a notificationId as a parameter (ex: GET /notification/1aeb9da8-075e-4885-ae42-a99dd40e92f6)

{
    "EntityId": "491b60d3-14f6-4464-ab43-bb1e51949c3a",
    "NotificationId": "359b1695-1df0-4516-83e3-25b8bcf63620",
    "Event": "Customer_Updated",
    "TimeStamp": "637103769211700000",
    "EntityLocation": "api/v1/customer/10023"
}

Notification feedback

When receiving a notification it is best practice to respond to this by providing a feedback to Visma.net that you’ve received and handled the notification. This feedback will be visible in the Visma.net user interface and provide the user with important feedback that the notification is handled.

You provide the feedback by sending a POST-request to the endpoint /WebhookNotificationFeedback.

The body should include the following JSON-body:

{
  "notificationId": "826fa9b4-247e-47bf-8f56-010c8dba27e9",
  "source": "My integration",
  "description": "Notification received and handled",
  "isSuccess": true
}

The body contains the following data-properties:

Name	Description
notificationId	The unique Id for this notification
source	A freetext field used to identify your integration as the receiver
description	A freetext field used to provide a message
isSuccess	Boolean value to indicate if the notification could be handled correctly or not

You could provide multiple feedbacks for each notification if useful.

- How to Set up Webhooks in the Financials ERP UI

- How to Set up Webhooks in the API

[David Tandberg-Johansen]

Hi,

What about Branches, is it possible to differentiate on Branches?

[PetterSvensson]

Hi,

What makes a notification end up in the "failed" section? Is it if Visma fails to publish it, like if Visma is temporarily down? Is it also if the receiver fails to handle it and reports isSuccess = false? What happens if Visma is down for whatever reason?

Thanks! 🙂

[PetterSvensson]

Another question: I'm interested on finding out changes on CustomerInvoices, specifically "dunningLetterLevel"? Will that be covered by the "Ar Invoice"?