Skip to main content

Integration Triggers

Integration triggers allow you to define when an instance 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:

Set static integration trigger in Prismatic app

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:

Configure integration trigger to use config variable in Prismatic app

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

Set config variable for integration trigger in Prismatic app

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 (or GET) 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"

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, as input for the integration's steps.

Set webhook trigger via POST request in Prismatic app
The GET verb is supported

You can use the GET verb to invoke an instance, but note that the GET verb does not allow you to send data with your request. If you need to send data with your request, use the POST verb.

The GET verb was introduced because some applications send a GET request when a webhook is configured to verify that the webhook endpoint is ready to receive requests.

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" \  ''

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

Customize webhook trigger response code in Prismatic app

Webhook Endpoint Configuration#

Webhook triggers can be configured for in integration in one of three ways:

  • Instance and Flow Specific: Each flow on each instance gets its own unique endpoint. This is the default configuration.
  • Instance Specific: Each instance gets a unique endpoint, and the integration determines which flow to run based on header or payload data.
  • Shared: All customers' instances of the integration share an endpoint. Data in the header or payload determines which customer and flow should run.

For information on configuring and troubleshooting webhook endpoints, see our Endpoint Configuration article.

Sending Data to Webhook Triggers#

A webhook parses data from the following sources:

  • The request body - the JSON (or other) data that is sent to the webhook as an HTTP request body.
  • The request headers - the HTTP headers.
  • The URL path - The path to resource that follows the integration webhook URL.
  • The URL parameters - The parameters that follow the ? in a URL..

Take, for example, this curl invocation:

curl \  '' \  --header "header-one: First header value" \  --header "header-two: Second header value" \  --header "Content-Type: application/json" \  --data '{"Payload Key 1":"Payload Value 1","Do Thing?":true,"quantity":123}'
  • The request body - {"Payload Key 1":"Payload Value 1","Do Thing?":true,"quantity":123} - is parsed (if JSON) and is accessible to the integration by referencing the trigger's Non-JSON payloads (like XML, images, etc) are accessible through results.rawBody and can be parsed in subsequent steps that handle that type of data.
  • The request headers are accessible through the trigger's results.headers.HEADER-NAME.
  • The url path - my/custom/path - is accessible through the trigger's results.pathFragment. You can pass that data into the built-in split string action and split on the / character to split the URL path into an array ['my','custom','path'].
  • The url parameters - ?param-one=ParamValueOne&param-two=ParamValueTwo are parsed and accessible through the trigger's results.queryParameters.PARAMETER-NAME.
Screenshot of Sending Data to Webhook Triggers

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'

The binary file can be accessed by subsequent steps by referencing

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

The first name in this example is accessible by referencing, and the avatar image is accessible by referencing

Post multipart data with webhook triggers in Prismatic app

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:

Access webhook URLS for integration in Prismatic app

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.

If you use shared endpoint configuration, the shared endpoint URL is accessible from results.invokeUrl.

If you set up API keys for your deployed instances, you can access results.webhookApiKeys similarly. An instance's flow can have multiple API keys assigned to it, so each results.webhookApiKeys.MY FLOW NAME is an array. You will likely reference the first API key, results.webhookApiKeys.MY FLOW NAME.0.

Validating Webhook Payloads with HMAC#

Hash-Based Message Authentication Code (or HMAC) is an authentication mechanism often used by webhook providers to verify that a webhook message is legitimate. It helps to ensure that messages sent to a webhook endpoint originated from a particular third-party, and not from some bad actor on the internet.

How does HMAC Work?#

HMAC implementations can differ slightly from one another, but generally speaking when a webhook request is sent to an endpoint, the request's body is hashed using a secret key and hash function. The resulting hash is sent with the webhook HTTP request as an HTTP header.

When the webhook endpoint receives the HTTP request, it also generates a hash using same secret key and hash function. If the hash the receiver generates matches the hash that the sender sent, the webhook request is processed. If they don't match, the request is rejected.

In order to spoof a webhook request, someone would need to know the secret key that only the sender and receiver know. Without the secret key (even if a bad actor intercepted the webhook request), it'd be nearly impossible for a bad actor to reverse engineer the hash and send spoofed requests to a webhook endpoint.

Generating an HMAC Hash#

You can configure your app to compute HMAC hashes and send them alongside your webhook requests. To generate a hash, you need three things:

  1. A request's body to hash. The body can be any format (JSON, XML, CSV, etc). For our example, let's say we have a JSON message that reads {"item":"widget","quantity":5,"customer":"abc-123"}.
  2. A secret key that only the third-party and Prismatic knows. For our example, we'll generate a random UUID string - "AC49CB66-511F-4085-9119-360B1B142F4B"
  3. A hash function to use (like MD5, SHA1, etc.). The industry standard (which APIs like Dropbox, Shopify, Slack, etc. all use) is SHA256 - we'll use that for our example, too.

Next, reach for an HMAC library for the language that your app is written in (most modern languages have an HMAC or crypto library). Here's a few examples in a variety of languages:

HMAC example written in Python3
import hmacimport hashlib
secret = bytes("AC49CB66-511F-4085-9119-360B1B142F4B", "UTF-8")message = '{"item":"widget","quantity":5,"customer":"abc-123"}'.encode();
hash =, message, hashlib.sha256)
print(hash.digest().hex()) # dc838d5b2ee53f55b5bcd77271505f52cd4c6c5123a867d9088fb70ac580f5bf

Regardless of which language you use to generate the HMAC hash, you get the same result for our example - dc838d5b2ee53f55b5bcd77271505f52cd4c6c5123a867d9088fb70ac580f5bf. You can then pass the hash as an HTTP header to our Prismatic webhook URL.

curl \  --request POST \  --header "my-hmac-header: dc838d5b2ee53f55b5bcd77271505f52cd4c6c5123a867d9088fb70ac580f5bf" \  --header "content-type: application/json" \  --data '{"item":"widget","quantity":5,"customer":"abc-123"}'

Can I include the HMAC hash in the body instead? That's a common question, and the answer is a resounding no. By adding the HMAC hash to the body, you change the body... so a different body hash is computed... which requires you to change the body... (GOTO 10). An HMAC hash should be sent via a header.

Validating HMAC Hashes in a Trigger#

If your HMAC hash is generated from the HTTP payload's body, the secret signing key is a string, and the hash is included as a header, you can use the built-in HMAC Webhook Trigger to validate payloads. Configure the trigger by setting the name of the header that contains the HMAC hash (e.g. x-hmac-sha256), the hashing function you used (e.g. sha256), and the secret key you used, and the trigger will accept payloads that are properly signed, and throw an error when payloads are not signed correctly. The trigger otherwise operates like the standard built-in webhook trigger.

If the app you're integrating with deviates from standard HMAC signing practices, or if you need to respond to webhook requests with dynamic responses, you can build your own custom trigger that handles HMAC validation. Slack, for example, includes an additional parameter (a timestamp) in its HMAC computation, and expects a custom response from the webhook endpoint. You can read about how the Slack webhook trigger works in this quickstart.

Instance Deploy Trigger#

An integration flow can be configured to be run when an instance of the integration is deployed. To do that, click your trigger and then click CHANGE TRIGGER. Choose to replace your trigger with a Management Triggers - Instance Deploy trigger. 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

Instance Remove Trigger#

The opposite of an instance deploy trigger is an instance remove trigger. Flows with this trigger run when an instance is removed (deleted), and can be used to clean up webhooks and other configuration that an instance deploy trigger created.

Custom Triggers#

You can build your own triggers as part of a custom component. This is helpful if you need to generate dynamic responses to webhook requests, or do HMAC or other payload validation before your integration runs.

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, you will see this when you invoke the integration synchronously:

curl '' \  --data '{}' \  --header "Content-Type: application/json" \  --header "prismatic-synchronous: true" \  --location
{"id":1,"name":"Leanne Graham","username":"Bret","email":"","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":"","company":{"name":"Romaguera-Crona","catchPhrase":"Multi-layered client-server neural-net","bs":"harness real-time e-markets"}}

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

Toggle execution configuration for integration in Prismatic app

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

Synchronous Invocations and Redirects#

When you invoke an instance synchronously, the output of the final step of your integration is written to Amazon S3. The HTTP request that invoked the integration execution then receives a response that redirects them to the file in Amazon S3. We do this because Amazon's API Gateway has a 10MB limit on HTTP responses, and step results may exceed 10MB - S3 has no such size limit.

Because of this redirection, you should make sure that your request library is configured to follow HTTP status code 303 redirects. For curl, for example, include a -L / --location flag so it follows redirects.

If the party initiating the instance execution request does not support following redirects, they can pass an optional header, prismatic-prefer-direct-sync-json-response: true with their request to skip the redirect to S3, and return the response directly. Note: This only works for step results less than 5MB in size, and your last step's results must be serializable as JSON (i.e. not a binary file). If your final step's output is greater than 5MB, they'll be redirected to S3. This works well if your final step's results is plain text or JSON.

Skip the redirect to Amazon S3
curl '' \  --header "prismatic-synchronous: true" \  --header "prismatic-prefer-direct-sync-json-response: true" \  --request POST \  --data "{}"

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.

Configure HTTP status codes for synchronous integrations in Prismatic app
$ curl '' \   --verbose \   --location \   --header "prismatic-synchronous: true"
* TCP_NODELAY set* Connected to ( 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"

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