Skip to main content

Integration Triggers

Integration Triggers#

Integration triggers allow you to define when an instance of an integration should run. There are several types of triggers, with schedule triggers and webhook triggers being the most commonly used. Many components include triggers that do things like validate webhook payloads, preprocess data, or return custom responses to the webhook caller. You can also configure a deploy trigger that runs when your integration is deployed to a customer.

  • If you are integrating with a particular app or service, and that service has a component with a trigger, use that trigger.
  • If you would like your integration to run on a predefined regular basis, you should use a schedule trigger.
  • If you would like to invoke your integration from another system that can make HTTP calls, you should use a webhook trigger.
  • If you have a flow that you would like to run when an instance is deployed, use a deploy trigger.

If your integration has multiple flows, each flow has its own trigger (and so its own webhook URL or schedule).

You can always change which trigger your flow uses by clicking on the trigger, and clicking the CHANGE TRIGGER button in the drawer that appears.

Scheduled Triggers#

Scheduled triggers allow you to create a regular schedule to dictate how often your integration should run. This is useful if you have an integration that should be triggered consistently at a specific time. You can set up your integration to run at the same time for all customers, or you can set up schedules on a per-customer basis.

To set up the same schedule for all customers, click the integration's trigger, open the Schedule tab, and enter the schedule you would like your integration to follow. You can configure your integration to run every X minutes, hours, days, or weeks:

You can alternatively select Custom and provide a cron string. For example, a trigger of */5 8-16 * * 1-5 would cause your integration to run every five minutes during business hours (8:00-16:55), Monday through Friday. For help computing a cron schedule, see this Cron Calculator.

To configure schedules on a per-customer basis, first create a config variable of type Schedule by clicking the Config Variables button. You can give your config variable any name you choose:

Then, click your integration trigger and reference the Config Variable you created:

When your integration deployment team later deploys an instance of your integration, they can configure a custom schedule for that instance.

Webhook Triggers#

Webhook triggers allow you to run a particular instance or flow of an instance by making an HTTP POST request to the webhook's URL. This is useful if you would like an outside application to invoke an integration when something within the outside application occurs. The outside application can assemble some data, and send that data to a Prismatic webhook URL via an HTTP POST request.

For example, third-party software could invoke an instance with a JSON payload whenever a job in the third-party application is complete, like this:

curl \  --data '{"renderId":51266,"s3Bucket":"test-customer-renders","status":"complete"}' \  --header "Content-Type: application/json" \  'https://hooks.prismatic.io/trigger/EXAMPLE1FjMmUtOWNiZS00MmI3LTllYzEtMDQzYjY5ZDkxNThj'

Note that the payload of the POST request is available by referencing the integration's trigger, shown in the screenshot below. Steps can then reference data from the webhook payload, like integrationTrigger.results.body.data.renderId, as input for the integration's steps.

Webhook Trigger Responses#

By default, webhook triggers provide an HTTP code 200 ("OK") response to callers of the webhook. The response body contains an execution ID, which can be used later to get logs and step results from the Prismatic API. The response looks like this:

curl \  --data '{}' \  --header "Content-Type: application/json" \  'https://hooks.prismatic.io/trigger/EXAMPLE'
{"executionId":"cd794a44-5edb-44ec-bf9e-d945a464fd21"}

You can customize the response by clicking the integration webhook trigger and selecting a different HTTP code, response body, or response content type:

Webhook Endpoint Configuration#

Webhooks endpoints can be configured in one of three ways, depending on your needs. When deciding on a webhook endpoint configuration, ask yourself two questions:

  • Do my webhook endpoints need to be the same for each of my customers, or can customers be configured to use different webhook endpoints?
  • If my customers can have unique webhook endpoints, can they be configured to have unique webhook endpoints depending on what activity they're responding to? For example, if your third-party app invokes an integration when it has an inventory update, and when a new order is created, can those two activities invoke distinct webhook endpoints?

Once you have answers to those questions, you can choose one of the following webhook endpoints configurations for your deployed instances:

Instance and Flow-Specific Endpoint Configuration#

This is the default configuration. When an instance of an integration is deployed to a customer, each flow within the instance is assigned its own webhook endpoints. Invoking that URL causes that specific flow of that specific instance to run. You could have a unique webhook endpoints for the "Update Inventory" flow for each customer, and another distinct URL for the "Order Created" flow.

Instance-Specific Endpoint Configuration#

When an instance of an integration is deployed to a customer, that instance is assigned a single webhook endpoint. If the integration contains a single flow, that flow is invoked when the webhook URL is called. If the integration contains multiple flows, the flow's name that you want to execute must be specified, either as part of the HTTP webhook payload or as an HTTP header.

Shared Endpoint Configuration#

All customers that have an instance of a particular integration deployed to them share a webhook endpoint, and data is routed to the proper customer / flow based on data contained in the HTTP POST request. The webhook invocation must include an external customer ID and flow name either in the HTTP payload, or as HTTP headers. The data payload sent to the shared webhook endpoint is passed on to the specified customer's instance's flow's integration trigger.

Preprocess Flows and Routing Webhook Requests#

To configure endpoint configuration, click the Endpoint Configuration button on the right of the integration designer screen.

From this drawer you can select your Endpoint Type, and configure how Prismatic should determine which customer / flow to route the webhook request to. If the external customer ID or the flow's name are presented to the webhook as HTTP headers, those headers can be referenced by Flow Name and External Customer ID input fields, similar to how step inputs can reference trigger payloads. Within the Endpoint Configuration drawer you can reference things like results.headers.example-customer-id-header. You can similarly pass external customer ID or flow name to the shared webhook endpoint as part of the HTTP request's body, and dispatch the instance invocation based on the request body's values by referencing things like results.body.data.example-customer-id-key.

If flow name or customer ID need to be looked up, or if there is other processing you need to do prior to dispatching data to a specific customer's flow, you can optionally designate a flow in your integration to be a Preprocess Flow, meaning that it'll process some webhook payload and header information prior to invoking a specific customer's flow. You can use output from the final step of the preprocess flow as inputs to identify External Customer ID and Flow Name:

For an example of how a preprocess flow works to determine the customer ID and flow name to dispatch to, check out our quickstart tutorial on Using Shared Webhooks and Preprocess Flows.

Posting Binary Data with Webhook Triggers#

If you have binary data (like an image or PDF) that you would like to post as part of your webhook invocation, you can pass that binary data in as part of your request. For example, if you have an image, my-image.png, you could invoke a test of an integration with:

curl \  --request POST \  --header 'Content-Type: image/png' \  --data-binary '@/path/to/my-image.png' \  'https://hooks.prismatic.io/trigger/EXAMPLEuY2U6MmE2ODg4NTEtM2EwZS00NjAzLTljMDAtY2FmMGNlNDc3ZDBj'

The binary file can be accessed by subsequent steps by referencing integrationTrigger.results.body.data.

Posting Multipart Data with Webhook Triggers#

It's useful to be able to post a combination of binary and text data to a Prismatic webhook. For example, you might want to post information about a person, as well as an avatar image of the person, to be processed by an integration. To do that, use a content type of multipart/form-data with your webhook invocation:

curl \  --request POST \  --header "Content-Type: multipart/form-data" \  --form person='{"firstname":"Taylor","lastname":"Reece"};type=application/json' \  --form photo=@taylor.png \  'https://hooks.prismatic.io/trigger/EXAMPLEuY2U6MmE2ODg4NTEtM2EwZS00NjAzLTljMDAtY2FmMGNlNDc3ZDBj'

The first name in this example is accessible by referencing integrationTrigger.results.body.data.person.firstname, and the avatar image is accessible by referencing integrationTrigger.results.body.data.photo:

Accessing Webhook URLs in an Integration#

An integration is aware of its own webhook URLs, and those URLs are accessible by referencing the trigger's results.webhookUrls object:

This comes in handy if you need to configure a third-party service to send data to your webhooks. A common pattern is for one flow of your integration to be run when an instance is deployed using a deploy trigger. That deploy-time flow can set up webhooks in a third-party app by referencing its trigger's results.webhookUrls values. Then, the third-party app will invoke the other flows of the integration when it needs to.

Deploy Triggers#

An integration flow can be configured to be run when an instance of the integration is deployed. To do that, select the integration trigger and under Type select Deploy. This will cause your current flow to run whenever the integration is deployed as an instance to a customer.

This is handy if your integration needs to complete a series of tasks when its deployed. For example, your integration might need to configure a third-party app to send data to the other flows' webhooks. Or, your integration might need to enable features in a third-party app or create a series of directories in a file share before the integration is invoked.

If there are tasks that need to occur when an instance is deployed, set up those tasks as a flow and configure the trigger to run at deploy time.

For More Information: Multiple Flows with a Deploy Trigger

Synchronous and Asynchronous Integrations#

Integrations are configured by default to run asynchronously. That means that whenever an integration is invoked by trigger webhook URL, the integration begins to run and the system that invoked the integration can go on to complete other work. This is the most common case for integrations - you want to start up an instance when some certain event occurs, but you don't want to wait around while the instance runs.

Sometimes, though, it's handy for an application to get information back from the instance that was invoked. For example, you might want your proprietary software to wait until an instance runs to completion before completing other work. In that case, you can choose to run your integration synchronously. Then, when your software makes a call to the instance's webhook trigger URL the HTTP request is held open until the instance run is complete.

When you choose to run your integrations synchronously, the HTTP request that invokes an instance returns a redirect to a URL containing the output results of the final step of the integration. For example, if the final step of your integration pulls down JSON from https://jsonplaceholder.typicode.com/users/1, you will see this when you invoke the integration synchronously:

curl \  --data '{}' \  --header "Content-Type: application/json" \  --header "prismatic-synchronous: true" \  --location \  'https://hooks.prismatic.io/trigger/EXAMPLE'
{"id":1,"name":"Leanne Graham","username":"Bret","email":"Sincere@april.biz","address":{"street":"Kulas Light","suite":"Apt. 556","city":"Gwenborough","zipcode":"92998-3874","geo":{"lat":"-37.3159","lng":"81.1496"}},"phone":"1-770-736-8031 x56442","website":"hildegard.org","company":{"name":"Romaguera-Crona","catchPhrase":"Multi-layered client-server neural-net","bs":"harness real-time e-markets"}}
Configure synchronous requests to follow redirects

When you invoke an instance synchronously, your request is accepted, and then is redirected to a URL containing the response payload. Make sure your request library is configured to follow redirects.

For curl, for example, omit the -X or --request POST flags since they override the HTTP verb used on the redirect, and include a -L / --location flag so it follows redirects.

You can toggle if your integration is synchronous or asynchronous by clicking the Execution Configuration button on the right side of the integration designer.

You can also pass in a header, prismatic-synchronous with a webhook invocation to instruct your instance to run synchronously or asynchronously:

curl \  --header "prismatic-synchronous: false" \  --request POST \  'https://hooks.prismatic.io/trigger/EXAMPLE'

HTTP Status Codes for Synchronous Integrations#

When an instance is configured to run synchronously or is invoked synchronously with the prismatic-synchronous header, the HTTP response returns a status code 200 - OK by default. It's sometimes useful, though, to return other HTTP status codes. For example, if a client submits wrongly formatted data to be processed by an instance, it might be helpful to return a 406 - Not Acceptible or 415 - Unsupported Media Type.

To accomplish this, you can configure the final step of your integration to return a different status code. Most commonly, you can add a Stop Execution step to the end of your integration, and specify an HTTP response that it should return.

$ curl  \   --verbose \   --location \   --header "prismatic-synchronous: true" \   'https://hooks.prismatic.io/trigger/SW5zdGFuY2U6ODU4MDdiNDEtYjQ5Zi00NDIyLTgwNTctNjc0ZmI5MmQ4N2Ey'
* TCP_NODELAY set* Connected to hooks.prismatic.io (13.227.37.2) port 443 (#0)
...
< HTTP/2 415

If you would like to return HTTP status codes from a custom component at the end of your integration instead, return an object with a statusCode attribute instead of a data attribute:

return { statusCode: 415 };

Synchronous Call Limitations#

Response Body and Status Code Limitations#

When an integration is invoked synchronously, the integration redirects the caller to a URL containing the output results of the final step of the integration. If the final step of the integration is a Stop Execution action, or any custom component action that returns a statusCode, the redirect does not occur and the caller receives a null response body instead.

API Gateway Size and Time Limitations#

AWS API Gateway times out requests after 29 seconds, and our maximum response size is 500MB. So, to get a response from an instance that is invoked synchronously, please ensure that your integration runs in under 29 seconds and produces a final step payload of less that 500MB.

If your integration regularly takes over 29 seconds to run, or produces large responses, we recommend that you run your integrations asynchronously instead. When you invoke an integration asynchronously you receive an executionId:

curl \  --data '{}' \  --header "Content-Type: application/json" \  'https://hooks.prismatic.io/trigger/EXAMPLE'
{"executionId":"cd794a44-5edb-44ec-bf9e-d945a464fd21"}

That execution ID can be exchanged later with the Prismatic API for logs and step results using the executionResult GraphQL mutation.