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 with 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 tries 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
picture of example code

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 three 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 five 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

CHANNEL
A channel represents a domain concept which is used to exchange data between integrating applications. (e.g., e-filing)
SCHEMA
Schema is a contract written by the publisher outlining the details of data they will be publishing to a Channel. Publishers can provide multiple schemas on the same channel (think of one schema as “create,” one schema as “update”, one schema as “delete “, for example). Each published message is validated against the relevant schema.
PUBLISHER
A publisher is application, service, or system that pushes data to a Channel.
SUBSCRIBER
A subscriber is application, service, or system that receives data from a Channel.
EVENT
A unit of payload that carries data across a channel ((e.g., e-filing 52 completed at 2pm on Tuesday)
WEBHOOK
Endpoints registered against a channel (e.g., customer e-filing https callback)
ACTION
Independent activities that could occur in the concept (e.g., e-filing started, completed)
CUSTOMER
Thomson Reuters’ customers
CLIENT
Customer’s customer (e.g., Firm’s customers)

This article applies to:

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

error-icon

Triva isn't available right now.

Check out the support page for our phone number and hours

error-close