Web hooks allow one application to perform an action when another application performs an action. Instead of Application A continually polling Application B to see if it needs to do something with a web hook Application B waits until notified by Application A that it needs to do something.
It's important to note that using web hooks can be a pretty technical process that involves coordinating authentication and hand shakes between two or more environments. Therefore it is best to use web hooks only if you have the technical expertise to perform the required steps, including writing custom code and building the supporting application infrastructure. This technical document is written under the assumption that the reader has a technical background required to complete these tasks.
This article will cover the following topics:
Before starting a custom web hook you will need two things referenced in this document:
Business ID: the unique identifier of the business for the TRYTN system. This can be found in a notice on the API keys page, located at Settings > Integrations > API Keys.
API Key: the secret key that authenticates a web hook subscription. This can also be found in the API Key section located at Settings > Integrations > API Keys. You can also learn more about API keys at this support document.
Registering a Web Hook
All web hooks interact with the TRYTN API and the TRYTN API requires token authentication for all interactions. In order to retrieve an authentication token you must have and use an API key.
Create a POST request to https://api.trytn.com/api/token with the following request body:
{
"secretKey": "{{your_api_key_secret}}"
}
If successful you will receive a 200 response that has the following response body:
{
"token": "{{api_authorization_token}}"
}
For each web hook topic you wish to subscribe to, create a POST request to https://api.trytn.com/api/{{your_business_id}}/webhooks with the following request body:
{
"businessId": "{{your_business_id}}",
"event": "{{topic_name}}",
"target_url": "{{your_web_hook_receiving_endpoint}}"
}
This request also needs the following headers:
{
"Authorization": "Bearer {{api_authorization_token}}"
}
Upon receiving this request the TRYTN infrastructure will POST to the target_url specified in the above request body. The target_url needs to fork into two paths: verification (recognized by eventType Microsoft.EventGrid.SubscriptionValidationEvent) and standard event reception. This document will cover both the recommended and alternative way to verify the web hook subscription.
Synchronous Response Verification (Preferred / Recommended)
The preferred way to automatically verify this request is to return a 200 response code with a specific response body. This response body will include a verification code that needs to be returned in the response from your server.
Upon hitting your server for the first time (and potentially additional times - thus requiring the fork to always verify if needed) an object is posted to your server with a body that looks similar to the following:
{
"event": {
"body": [{
"data": {
"validationCode": "{{validation_code}}",
"validationUrl": "{{validation_url}}"
}
}]
}
}
Within this, your system should take the validationCode property and within the 200 response return the following response body:
{
"validationResponse": "{{validation_code}}"
}
If successful the response back from this will be a 200 response with a single id string property. You are not required to store this string, however if you do not store the string you will be unable to programmatically deregister the web hook. Any error will be a 200 response with a single boolean property isInConflict set to true.
It's important to note that this is required to be a 200 response. a 202 response will not be allowed by the system. The entire handshake operation in this method is required to be completed in under 30 seconds. If it is not completed within 30 seconds the operation is cancelled and may be reattempted after 5 seconds. If multiple attempts fail it will be considered a validation handshake error.
Asynchronous HTTP GET manual verification (Alternate)
Some systems don't support a synchronous handshake or cannot return the validationCode in the response. In these instances after making the register POST call an object will be returned in response that looks similar in structure to this:
{
"event": {
"body": [{
"data": {
"validationCode": "{{validation_code}}",
"validationUrl": "{{validation_url}}"
}
}]
}
}
After receiving this response your server will need to perform a GET request to the validationUrl property in the response provided. This URL is only valid for 5 minutes, after which time the handshake will be considered a validation handshake error.
Deregistering a Web Hook
There are two methods to deregister a web hook: programmatically and via the TRYTN admin. Both work in a similar fashion and if you do not plan on bringing up and tearing down web hooks often then it may be beneficial to just use the TRYTN admin.
Programmatically Deregister
Create a POST request to https://api.trytn.com/api/token with the following request body:
{
"secretKey": "{{your_api_key_secret}}"
}
If successful you will receive a 200 response that has the following response body:
{
"token": "{{api_authorization_token}}"
}
Once you have the authentication token perform a DELETE request to https://api.com/api/{{your_business_id}}/webhooks with the following request body:
{
"businessId": "{{your_business_id}}",
"id": "{{id_of_web_hook_registration}}"
}
This request also needs the following headers:
{
"Authorization": "Bearer {{api_authorization_token}}"
}
This call will need to be made for each web hook you wish to deregister.
Deregister Through TRYTN Admin
Once logged in to the admin navigate to Settings > Integrations > Web Hooks. From there identify the web hook(s) you wish to deregister and select Actions > Remove. Note this action is immediate and permanent and will require a new handshake as mentioned above to turn the web hook back on.
Currently Supported Web Hook Topics
The following topics are currently supported via TRYTN web hooks. The table below lists each topic, when it is triggered, and expected sample data returned (not all inclusive.) Note the structure of objects can change at any time.
| Topic Name | Trigger | Sample data |
merchandise-new |
When one or more merchandise items are purchased. Once per item purchased. |
{
|
merchandise-refunded |
When one or more merchandise items are refunded fully. Once per item refunded. | |
merchandise-updated |
When one or more merchandise items are updated. Once per item updated. | |
scheduled-canceled |
When one or more scheduled item is cancelled. Once per item cancelled. |
{
|
scheduled-new |
When one or more scheduled item is purchased. Once per item purchased. | |
scheduled-updated |
When one or more scheduled item is updated. Once per item updated. | |
transaction-new |
When a new order is placed. |
{
|
transaction-updated |
When a transaction is updated or refunded in any way. | |
unscheduled-canceled |
When one or more unscheduled item is cancelled. Once per item cancelled. |
{
|
unscheduled-new |
When one or more unscheduled item is purchased. Once per item purchased. | |
unscheduled-updated |
When one or more unscheduled item is updated. Once per item updated. |