Artisan SVG > Webhook (webhook) (globe-2)
Artisan SVG > Webhook (webhook) (globe-2)

Webhook Trigger
2.3

Catch callouts for any service that offers sending a signal to a custom URL using the Webhook Trigger

Overview
Copy

A webhook (otherwise known as a web callback or HTTP push API), is a way for applications to provide other apps with real-time information. A webhook typically delivers data to other applications "as and when it happens", meaning you get data immediately.

The Webhook Trigger is designed to allow users to catch callouts for any service that has the option of sending a signal to a custom URL.

Setup & Authentication
Copy

Below is a summary of how the Webhook Trigger is configured.

While remaining as general as possible, occasionally Braintree has been used for demo purposes where need be.

1 - Locate the public URL
Copy

The Webhook Trigger's public URL is where all Webhook callbacks are sent. This is what allows Tray.io to receive data from a users service of choice.

The steps to find the Webhook Trigger's public URL are as follows:

  1. Create a new workflow and select the WebHook as your trigger.

  2. Click on the trigger step options and select 'Copy public URL':

2 - Configure settings (service side)
Copy

In order to work in tandem with the Tray.io, the Webhook Trigger needs to be associated with the selected service. This is where the Webhook's public URL comes into play.

Please be aware this is only a rough guide as it will vary from service to service.

The steps to send all callouts to your Webhook Trigger are as follows:

  1. Log in to your service of choice.

  2. Select 'Account Settings'. Note that this varies by service. Consider looking under 'Preferences', 'Security', 'API', etc.

  3. Select the relevant 'WebHooks' heading. This may also be under the name 'Apps & Credentials', 'API Links', and so on.

  4. Make sure the parameters needed and necessary privacy settings are selected.

  5. Add the Tray.io Workflow public URL to the target field.

Below is a sample of what users should be looking to achieve depending on their application. I.e, the Webhook public URL registered with the service in quesiton.

3 - Test authentication
Copy

Once the above steps have been followed, return to the workflow dashboard in order to test/ complete the trigger setup.

The steps to will be as follows:

1. Click the 'Enable' button found at the bottom-right of the workflow dashboard. Tray.io will now be actively listening for calls from any Webhook, whose target is the Workflow Trigger's public URL.

2. Navigate back to the service dashboard and deliberately provoke an event type. This needs to be one that the Webhook Trigger is configured to listen out for. Depending on the service, examples include customer creation, survey completion, declined payments etc. What is important is that regardless of the event type, users only provoke the trigger using a fake/ test event.

3. Some users may be lucky enough to be using a service which already provides a URL check (such as Braintree below):

4. Return to the workflow dashboard and click the Debug button. If the configuration is correct, users will be able to see a green entry within the workflow logs, containing the data from the test event:

Once setup is complete, any data which is received by the Webhook Trigger can be used and manipulated else where within the workflow, depending on a users needs.

Extracting data
Copy

Using and moving data from the Webhook Trigger works the exact same way as it does between connectors. This means that any enabled workflow with a Webhook Trigger can be used to send, receive and change the information to hand.

By targeting the right key/ value pair, via the use of jsonpaths and connector property panel options, users are able to manipulate the data sources to suit their needs.

For example, users could extract some of the data from the trigger by using a 'Send Email' connector. This in turn would forward the information on to another colleague as per the operation selected states. Note that interpolation has been used in this example.

Users can use this method to send data to Salesforce, Slack, or any other service. The only limitation is your imagination.

Triggering an Event Reply
Copy

It is possible to send a reply to the service which sent the webhook data to your workflow, by using the 'Await workflow and respond' operation.

For example, after taking steps to process the data received, users may wish to respond with a 200 status and a "Successfully Recorded" message in the body.

Or, after making an unsuccessful boolean check for a user or valid url, you may wish to respond with a 404 'not found' message.

Please see our Trigger Event Reply documentation for details.

There is a limit of 1MB for the total response size

If the combined size of the 'status', 'body and 'header' in a trigger event reply step is larger than 1MB then the request will fail with the following message:

{"message": "Unfortunately, we encountered an internal error. Please contact us if the problem persists. Error ID: 81a6941aae"}

This will result in several retries with an eventual 504 error as the retries will take longer than 5 minutes:

Security
Copy

Service
Copy

It is highly recommended that users secure their Webhook using the permission settings and unique identifiers available service side. This is to help make sure that users only receive requests from trusted sources and accounts/ individuals.

The options available to users will vary depending on your use case and the service itself (such as challenge codes, hashes, account ID's etc).

Tray.io
Copy

It is highly recommended that users secure their Webhook via the use of a CSRF token.

This is an advanced settings feature, and more details can be found under the below CSRF tokens heading.

CSRF tokens
Copy

A CSRF token is a unique hash usually generated by the server-side application (or service). This is then transmitted to the client (aka Tray.io). When the request is made, the service validates that the request includes the expected CSRF token. This is a continuous enabled check.

The security token will need to be matched with X-CSRF-TOKEN HTTP header value passed by the client, in order to successfully trigger the workflow.

Any calls which do not contain the X-CSRF-TOKEN header, or contain an incorrect value, will receive an Invalid value for header: X-CSRF-TOKEN response.

As a best practice, CSRF Token should be added by creating a Generic service authentication.

Then you can refer to the token using $.auth jsonpath rather than hardcoding the token in plain text on the Trigger.

Test your security setup by using an API development environment such as Postman. Make a POST request to your Webhook Trigger public URL and add the same CSRF token as a header:

The output in the Debug panel should display the header as expected:

Webhook technical limitations
Copy

Payload size limitations
Copy

The typical size limit for a basic Webhook payload is 1MB.

File content can also be sent as multi-part http requests instead. These would have an overall size limit of 10MB.

Rate limiting
Copy

While the basic 'Auto respond with 200' operation is not, the 'Validate and respond' and 'Await workflow and respond' operations are subject to rate limiting.

If too many requests (i.e. several hundred per second) come in to your webhook trigger at once, Tray.io will respond with an HTTP 429 (too many requests) error.

Please be sure to throttle requests appropriately at the source third-party service.

Enabling CORS
Copy

For webhook requests originating from within the browser, users need to enable the CORS feature.

CORS is a system that allows browsers to send data to Tray.io across domains without triggering errors. This setting also adds a few headers to the Tray.io response, from the Tray.io webhook.

CORS is automatically turned off on by default. This will have implications on whether or not the webhook is be able to work with other browsers.

To enable CORS features, users must make sure 'Allow webhooks from browsers?' is checked within the advanced properties section. This is found behind the 'Show advanced properties' button on the input panel.

This option is only available for the following two operations. There is a notable difference between what happens when this feature is enabled, depending on the operation selected.

1. Validate and respond

By enabling CORS with this operation, following three headers are added to the request:

  • Access-Control-Allow-Origin

  • Access-Control-Allow-Headers

  • Access-Control-Allow-Methods

2. Await workflow and respond

When users have the CORS checkbox ticked when using the "await workflow" option, the trigger correctly sends back the response to the browser for a preflight request.

The workflow is kicked off, but the response will not be sent back. You need to add the necessary access control headers manually in the trigger event reply connector.

Timeout
Copy

Users can set the number of milliseconds the Webhook Trigger will wait before timing out the incoming request.

This option is found behind the 'Show advanced properties' button within the input tab.

Processing
Copy

If your workflow needs to do more than 5 min of processing then you will need to use SQS or the HTTP client to send a final response.

For example, say you have a Webhook trigger set to "Await workflow and respond". One where the processing seems to be moderately heavy. The max wait time before a timeout is 5 mins.

The suggested solution is to auto-respond with a 200 alongside a "Workflow processing" message.

You would then use the HTTP Client to post to a consuming URL when the workflow is complete. Or message SQS.

Essentially you will need to create a 2 step workflow is necessary: a Webhook and a HTTP/ SQS connector will act as your endpoint.

Operations
Copy

Auto respond with HTTP 200
Copy

This operation is not subject to rate limiting for requests coming in from a third-party

Regardless of what webhook request is received, the Webhook Trigger responds immediately with an HTTP 200 status code. This ensures execution but has no validation.

This is a fire and forget operation type, and is particularly useful for services that DO NOT have the option to retry webhook calls.

Use case
Copy

Having no validation in place means that the Webhook Trigger will always reply with a status code of 200, no matter what.

For example, the user has a theoretical service which does not retry webhook calls. This means that should the call 'fail' (i.e. return with any status code other than 200), the payload and data for that call will be lost.

Having an operation available that replies automatically with the 'correct' HTTP status code means that services with no re-try option like the one mentioned, will still be able to have their workflows run as expected without any payload losses.

Should the status codes pick up on anything wrong, it is recommended that users have a fallback in place within their workflows in order to handle this.

Validate and respond
Copy

This operation is subject to rate limiting. Please be sure to throttle requests appropriately in the source third-party service

A webhook request is received and validated. The Webhook Trigger responds to the webhook sender with a relevant HTTP status code.

This operation is best used when a service needs to check if the webhook has been successfully called or not. The Webhook Trigger will always reply with whatever HTTP status code is relevant to the current situation.

Services which are able to re-try webhook calls benefit most from using this operation.

Use case
Copy

Some services require clarification on how the webhook call is responding, ideally before continuing.

For example, a service may have called the Webhook Trigger but the call itself has failed some sort of validation test. The callback has returned a 400 code as a result. In theory, the service will automatically try to resend the call to make sure Tray.io gets the original payload as expected.

If the call continues to fail, and a successful status code is necessary before proceeding, ideally the service itself will have fallbacks in place in order to handle such an event.

If this is not the case, then Tray.io is able to catch the failed payload provided the user has put the correct implementation steps in place to handle such an event. This is highly recommended by Tray.io in order to prevent data loss.

Await workflow and respond
Copy

This operation is subject to rate limiting. Please be sure to throttle requests appropriately in the source third-party service

This allows you to configure your own response. A webhook request is received and the webhook trigger waits for the workflow to complete before replying.

This operation is best used when a service requires workflow completion, before checking to see if the webhook itself has been successfully called.

IMPORTANT!: This operation must be used in conjunction with the Trigger Event Reply connector. The response has to be sent / placed at the end of the workflow so that it is sent upon completion.

The operation checks that the payload is suitable, which in itself is its own form of validation, but does not return a HTTP status code. The workflow is then run. Upon successful completion of the workflow (aka, another validation type in itself), the Trigger Event Reply connector sends a response.

The lacking HTTP status code can be handled within the Trigger Event Reply connector step, as this connector has a 'Status' field available. The Trigger Event Reply connector needs to be placed at the end of said workflow, in order to send the response once the workflow is complete.

Services which are able to re-try webhook calls benefit most from using this operation.

Use case
Copy

Some services require the workflow to complete, before replying with a status code on how the webhook call is responding.

For example, a service may expect to call the Webhook Trigger and complete a series of workflow steps successfully before continuing, because it is the only way to collect the current payload, regardless of the HTTP status.

If the service is not able to catch the current payload - should the webhook reply with a non 200 status code - then the Tray.io workflow needs to collect the data for before responding. Otherwise the data would be lost.

In theory, if the call itself has failed some sort of validation test the service will automatically try to resend the call. This is to make sure Tray.io gets the original payload as expected. By having Tray.io handle the data collection before replying, both the payload and the status code is recorded without any data loss even if the call fails.