Technical requirements for push notification

The user of push notification service must provide Tax administration an interface to which the push notifications are sent through public internet. The interface must meet the following technical and security requirements:

• HTTPS REST/JSON interface which can be called from public internet.
• At the end of the interface URL-endpoint there must be a following predefined section: “/Notify/v1”. For example: https://{client host name}/Notify/v1
• Interface must accept only the specified JSON-notification calls in HTTP POST call’s body:

{
        "Environment": "FIP",
        "NotificationKey": 0,
        "NotificationType": "string",
        "SubscriptionId": 0,
        "Timestamp": "2021-04-22T12:01:33.478+02:00"
}

• Environment is a standard text that indicates the environment that is used. "FIP" is the production environment, "FIS" is the test environment.
• The interface must respond within 10 seconds to the notification call sent by the Tax Administration.
• The interface must respond with HTTP code 200 OK when the interface has successfully received the push notification call. This response is an acknowledgement of receiving the push notification for the Tax Administration. There should be no body in the response.
• The Vero API push notification service will attempt to send the same notification to the client system interface up to three times in case the interface does not respond or it returns a HTTP code other than 200 OK. After three attempts, the push notification service will not attempt to send the same notification anymore. An email about the failure is sent to the email address of the contact person submitted in the notification subscription. If a certain number of failures to receive notifications occur within a certain time-period, the delivery of push notifications will be interrupt and an e-mail message will be sent. The customer's system must determine the reason for the failure to deliver the notifications, fix the issue and then the push endpoint can be re-registered.
• The Tax administration does not guarantee the receiving of push notifications. The client system should regularly poll the ListNotifications interface and check that all notifications have been processed.
• The interface must support a "HEALTHCHECK" type notification and respond with HTTP code 200 OK immediately. This notification type is intended to check the functionality of the customer interface.
• The Vero API push notification service sends a "HEALTHCHECK" notification type when a new interface endpoint is registered. In addition, a health check can also be sent at other times to ensure the connection is working. The client system does not need to react to this other than responding with 200 OK.
• The client system can check the status of a Vero API push notification service registration by calling the ListSubscriptions interface. The push registration status indicates the status of the service, active = push notifications are being delivered, fail = connection to the client interface has failed and push notifications delivery is interrupted, pending = health check is in progress and push notifications are not being delivered to the client system.
• After the successful registration of the new push endpoint, the Vero API push notification service will send an email about the successful registration to the contact email address provided in the notification request. The sender address is DoNotReply@vero.fi. Please ensure that the email is received, so that even in case of exceptions or errors in the service, incoming notifications will be successfully received.
• The functionality of the customer's system interface must be monitored and those responsible for maintaining the interface must react and fix any issues in their own system.
• If you want to stop using the push notifications or need to update the endpoint of the client interface, the client system can make these changes by calling the RegisterPush interface. By sending an empty push endpoint (callbackURL), the delivery of push notifications is stopped. The previous address can be updated by sending a new endpoint via the RegisterPush interface.
• If there is a maintenance outage on the customer's system interface or a longer break is required, when push notifications cannot be received, push registration must be terminated for the duration of the outage. The client system must retrieve the notifications during the outage with the ListNotifications interface after the end of the outage. If the push registration is not terminated, the delivery of notifications is automatically terminated again after three attempts to send notifications.

Customer system interface security requirements

The data content of push notifications is not sensitive and does not contain personal data. The data content consists of only key technical information.

• The client system interface must use the HTTPS protocol and TLS 1.2 or higher.
• The interface must support one of the following Cipher suites:
  • TLS_AES_128_GCM_SHA256
  • TLS_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• The Tax Administration's push notification service sends calls to the customer's system from the Azure cloud service. The push notification service has no predefined IP-addresses. The client system must make the necessary firewall openings to allow network traffic to port 443 from public Azure addresses.
• The client system interface must use the mutual TLS/client certificate authentication procedure and request a client certificate from the caller during the SSL handshake. The certificate shall be verified to be issued by the Tax Administration. In this way, the client system verifies that the caller is the tax administration.
  • Require a client certificate authentication procedure from the interface callers.
  • The client program calling the Tax Administration interface will issue an initial certificate signed by the Tax Administration CA.
  • The client system must download the CA package of the issuer from Vero.fi and use it to authenticate the caller. The CA package can be downloaded here:
    IRServicesIssuingCAv1-chain.cacert.zip, (ZIP)
    • Note! The test and production environments have different CA.
• The client system interface must also be protected by a secret specified by the client system (API key).
  • The client system must submit a secret (API key) which is used when registering the push-endpoint. The secret (API key) is a base64 encoded string value of at least 32 characters in length.
  • The Tax administration sends this secret in the header 'Vero-callback-secret' for push interface calls. The client system must check that the header is used and that the value returned is the same secret which was given in the registration.