How to

    Registering Custom Webhooks at Scale with Tray Embedded

    webhooks
    scalability
    illustration template
    Pic of Zach Gay

    Zach Gay

    Solutions Architect

    You may find yourself needing to trigger a Tray workflow from an event in an end-service that does not have a pre-built connector. This blog post details how to register Tray workflows in those end-services at scale.

    When you use a pre-built Tray trigger connector, a lot of magic occurs behind the scenes to make sure your Tray workflows are triggered by events that occur in whatever end-service you are connecting to. For example, in Tray Platform, if you insert a Salesforce trigger with your Salesforce authentication to track account record creation, Tray will programmatically register in your Salesforce account that a Tray workflow should be fired off when an account is created. This same process occurs in Tray Embedded. When a solution instance is created, Tray will do that programmatic registration of those triggers using that particular end-user's authentication that is tied to their unique set of workflows.

    When you are connecting to an end-service that does not have a pre-built trigger connector for listening to an event, you will need to use the native webhook trigger and perform the necessary steps to register that webhook. This is easy to do on one-off occasions. However, it will become incredibly time consuming if you are doing this for an infinite and ever growing amount of customers. This blog post will delve into how you can set up a scalable architecture with Tray Embedded to save you and your company lots of time. Generally speaking, there are 4 routes you can possibly take to solve this problem*:

    • Route 1 - Require end-users to manually input the webhooks into the end-service

    • Route 2 - Register custom webhooks via a Tray workflow

    • Route 3 - Register custom webhooks programmatically in your application

    • Route 4 - Contract with Tray Professional Services to build the trigger connector

    *Note that these are not the only viable routes. You can these to springboard off of to create a route that best suits you and your business.

    Route 1 - Require end-users to manually input the webhooks into the end-service

    This is my least favorite route of the four routes. It requires the least amount of effort to implement from the integration builder's perspective. However, it may lead to lots of company time being used by your support teams if your end-users have trouble performing this registration themselves. Nevertheless, let's walk through how to present the end-user with a set of instructions and the unique webhook URLs for their integration in the Config Wizard.

    Informing the End-User how to Register their Unique Webhooks

    When you create a workflow using the native webhook trigger, the webhook URL that will be unique to the end-user will be exposed in the Config Wizard. On the screen where you are displaying this webhook URL, you will provide a written set of instructions on what the end-user needs to follow to have a functioning integration. Below is an example snapshot of what this could look like:

    Webhook Registration Instructions for End-Users

    Route 2 - Register custom webhooks via a Tray workflow

    This route makes use of the Solution Instance trigger to perform the webhook registration. Whenever a change is made to the solution instance (such as when the instance is enabled), this workflow will trigger to check if any webhooks need to be registered to the end-service. You can read more about the Solution Instance trigger in our documentation here.

    Once this workflow is triggered, you will want to use the GraphQL Client connector to perform a GraphQL call to the Tray Embedded API endpoint to retrieve the webhook URLs you care about registering. You have access to the Solution Instance ID and Tray User ID that the instance belongs to inside the env property that is accessible inside any workflow. You can read more about what properties exist on this env property in our documentation here. You can read more on how to filter for webhook URLs from the Tray Embedded API in our documentation here.

    To securely store the Tray Embedded Master Token that is used to perform this GraphQL call, read how to store this property in an authentication using the Generic Service in my other blog post here.

    After retrieving the webhooks, you will then need to follow the documentation provided by the end-service to perform API calls to successfully register the endpoints inside the workflow. You will want to perform an API call to check if the webhook has already been registered to the end-service. If such an API endpoint does not exist in the end-service, you will want to store which sourceWorkflowIds have already been registered for the end-user in a config property on the solution instance.

    Route 3 - Register custom webhooks programmatically in your application

    When the user clicks finish in the Config Wizard, Tray will publish a tray.configPopup.finish event via PostMessage for your application to hook into to perform various actions. If you are auto-enabling solution instances when a user completes the Config Wizard, you are likely already subscribing to this event in your application. You can read more about Config Wizard events in our documentation here.

    Once inside this event, you will then retrieve the webhook URLs via a GraphQL call to the Tray Embedded API endpoint. You will filter the GraphQL response to find webhook URLs you care about registering. If you have 5 workflows in your solution, but you only care about registering 2 of those workflows to the end-service, you will filter by sourceWorkflowId to programmatically select which workflows to register. You can read more about this process in our documentation here.

    After retrieving the webhooks, you will then need to follow the documentation provided by the end-service to perform API calls to successfully register the webhooks. In order to make use of the end-user authentication to the end-service provided in the Config Wizard, you will want to make use of the Call Connector API to perform the webhook registration. You will want to perform an API call to check if the webhook has already been registered to the end-service. If such an API endpoint does not exist in the end-service, you will want to store which sourceWorkflowIds have already been registered for the end-user in a config property on the solution instance.

    Route 4 - Contract with Tray Professional Services to build the trigger connector

    This route is the easiest of the four routes. You can request Tray Professional Services to build a trigger connector that will perform the magic behind the scenes much like any one of our other pre-built trigger connectors. If this route is best for you, please work with your Account Manager to get that contract solidified.

    Subscribe to our blog

    Related Posts

    Blog@2x

    Storing a Last Modified Time Stamp on a Solution Instance

    Read more