Webhook endpoint overview
GoFileRoom Events is a real time notification system that keeps your applications informed about important activities in your GoFileRoom environment. This article provides technical details for implementing webhook endpoints to receive these event notifications. A webhook (also called a web callback or HTTP push API) is a way for GoFileRoom Events to give customer applications near real time information about document activity, workflow activity, and other critical activities. A webhook sends data as it happens, meaning you get data immediately.
A webhook (also called a web callback or HTTP push API) is a way for
GoFileRoom
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
GoFileRom
, 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.
If accepted, the event should return any 2xx HTTP status code (200, 201, 202). Any non-2xx HTTP codes signify an endpoint error. The system will attempt to deliver each webhook event up to 3 times immediately. If all 3 attempts fail, the message returns to the queue and the endpoint status changes to UNHEALTHY. While UNHEALTHY, the system sends only HEARTBEAT messages every 10 minutes until the endpoint responds with a 2xx code. Messages remain queued for up to 2 weeks before being permanently lost.
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:
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.DISABLED
– endpoint has been automatically disabled after remaining UNHEALTHY for 2 weeks. All queued messages are permanently lost.The switch between
HEALTHY
and UNHEALTHY
state is performed automatically. An endpoint is marked UNHEALTHY
if message delivery fails after 3 immediate retry attempts. 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 that 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 turn on 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