Skip to main content

Integration Triggers

Integration Triggers#

Integration triggers allow you to define when an instance of an integration should run. There are two types of triggers: schedule triggers and webhook triggers. 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, you should use a webhook trigger.

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#

When an integration is published and an instance of the integration is created, a webhook URL is associated with that instance. Executing HTTP POST requests on that webhook URL results in the instance being triggered to run.

The webhook URL is printed on the instance's page in the web app, or can be viewed by running

prism instances:list --extended --output json

JSON-formatted arguments can be passed through HTTP headers to the webhook URL, and used as inputs for the actions of the integration 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 as output of the integration's trigger, shown on the left. Steps can then reference integrationTrigger.results.body.data.renderId, etc as a reference input.

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:

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.

How to Run Integrations Synchronously

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.