Skip to main content

Legal

Tax & Accounting

Trade & Supply

Risk & Fraud

News & Media

Books

Developers

Administration tasks

Webhook endpoint overview

A webhook (also called a web callback or HTTP push API) is a way for ONESOURCE to give customer applications near real time information. A webhook sends data as it happens, meaning you get data immediately.
Webhooks are unlike typical APIs, where you have to poll for data often to see changes. This makes webhooks much more efficient for both the publisher and subscriber by simplifying development work, cutting down on the number of API requests, and decreasing the network and processing demand.

Webhook endpoint

To receive events from ONESOURCE, you'll need to implement an HTTPS endpoint.
To add an endpoint:
  • Use the POST method for the endpoint to accept events.
  • If accepted, the event returns a 200 OK HTTP status code.
  • All other HTTP codes signify an endpoint error, and try to publish each webhook event up to 3 times before considering the event lost.
  • Endpoint accepts HEARTBEAT and Test messages without any special actions.

Webhook endpoint security

Use the HTTPS protocol when implementing a callback endpoint to encrypt all communication traffic between the event publisher and the callback. The system automatically adds an authorization header to all requests with a signed JWT Bearer token.
To validate a token signature, download a public certificate key from the following endpoints:
Certificate key
Region
URL
AMER
https://amer.api.transit-hub.thomsonreuters.com/webhooks/certificate/public
APAC
https://emea.api.transit-hub.thomsonreuters.com/webhooks/certificate/public
EMEA
https://apac.api.transit-hub.thomsonreuters.com/webhooks/certificate/public
The system can cache a certificate public key to improve overall performance for up to 10 minutes.

Code example for token validation (C# nuget package)

Example code
/// <summary>
/// Check if the JWT signature is valid.
/// </summary>
/// <param name="token">JWT sent with request.</param>
/// <param name="publicKey">Public key for signature validation.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>Is token valid</returns>
public async Task<bool> ValidateJwtSignature(string token, byte[] publicKey, CancellationToken cancellationToken)
{
var jwtHandler = new JwtSecurityTokenHandler();
var jwt = jwtHandler.ReadJwtToken(token);

try
{
    using (var rsa = RSA.Create())
    {
      rsa.ImportRSAPublicKey(publicKey, out _);

      var validationParameters = new TokenValidationParameters
      {
        ValidateAudience = false,
        ValidateIssuer = false,
        ValidateIssuerSigningKey = true,
        IssuerSigningKey = new RsaSecurityKey(rsa),
        CryptoProviderFactory = new CryptoProviderFactory
        {
          CacheSignatureProviders = false
        }
    };

    SecurityToken validatedToken;
    jwtHandler.ValidateToken(jwt.RawData, validationParameters, out validatedToken);

    return true;
}
}
catch (SecurityTokenExpiredException)
{
  return false;
}
catch (Exception)
{
  return false;
}
}

Fallback mechanism

In truth, ensuring that an HTTP endpoint is always available is unfeasible due to various factors including server maintenance and network issues. We actively monitor the status and availability of each Webhook endpoint using real messages, and when there's no activity from the Publishing product, we send out a Heartbeat service message. This Heartbeat, essentially an empty message, is sent regularly to check if the endpoint is accessible.
There are 3 possible statuses for a Webhook endpoint:
HEALTHY
– everything working as expected.
UNHEALTHY
– unable able to deliver some of the messages.
The switch between
HEALTHY
and
UNHEALTHY
state is performed automatically. An endpoint is marked
UNHEALTHY
if message delivery fails on some messages. After successful delivery of 5 consecutive messages, the status is changed back to
HEALTHY
.

Heartbeat messages

A Heartbeat message can be identified using the schema value
HEARTBEAT
. The callback endpoint should always accept the Heartbeat message and return a 200 OK HTTP status code as a reply.

Webhook configuration

Schema Browser is used to help you understand, verify, and validate the content of the events being published.
Select
Product
 and
Channel
 to view schemas.

Webhook administration

This is currently being taken care of by Thomson Reuters on the Transit Hub Application.

Glossary

Term
Definition
Channel
A channel represents a domain concept which is used to exchange data between integrating applications. (for example, e-filing)
Schema
Schema is a contract written by the publisher outlining the details of data they’ll be publishing to a Channel. Publishers can provide multiple schemas on the same channel (think of 1 schema as “create,” 1 schema as “update”, 1 schema as “delete “, for example). Each published message is validated against the relevant schema.
Publisher
A publisher is an application, service, or system that pushes data to a Channel.
Subscriber
A subscriber is an application, service, or system that receives data from a Channel.
Event
A unit of payload that transfers data across a channel (e-filing 52 completed at 2pm on Tuesday)
Webhook
Endpoints registered against a channel (for example, customer e-filing https callback)
Action
Independent activities that could occur in the concept (for example, e-filing started, completed)
Customer
Thomson Reuters’ customers
Client
Customer’s customer (Firm’s customers)

VPC enhancements

The new VPC enhancements enable ONESOURCE Events to use dedicated gateways for internet connectivity through VPC. This facilitates the transmission of events to you while improving security and performance.
If you configured any specific internet addresses in your applications or security rules that restrict access using IPs, you'll need to update them. Our change reduces the number of IPs that you need to add to your allowlist, where your application only accepts from limited IPs.
Refer to the following list of IPs.
AMERs
  • 20.81.168.101
  • 20.151.232.150
  • 20.46.225.27
  • 52.229.67.149
  • 13.91.17.178
  • 20.84.80.196
EMEA
  • 20.77.247.218
  • 20.68.249.137
  • 51.105.243.233
  • 40.113.40.7
  • 51.116.82.110
  • 51.116.103.39
APAC
  • 52.243.99.13
  • 20.70.178.233
  • 104.43.57.11
UAT
  • 20.81.168.101
  • 20.151.232.150
  • 20.46.225.27
  • 52.229.67.149
  • 13.91.17.178
  • 20.84.80.196
  • 20.57.26.238
  • 52.232.135.109
  • 168.61.74.7
  • 20.46.235.3
  • 20.115.50.218

This article applies to:

  • Product: ONESOURCE Income Tax Express RS
  • Subject: Setup
Chat now

error-icon

Triva isn't available right now.

Check out the support page for our phone number and hours

error-close