Skip to main content

Endpoint Configuration

Webhook triggers can be configured for an integration in one of three ways, depending on your needs:

  • 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.

When deciding on a webhook endpoint configuration, ask yourself two questions:

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

Once you have answers to those questions, you can choose the appropriate webhook endpoint configuration.

Selecting Endpoint Configuration#

To configure your integration's endpoint settings, click the Endpoint Configuration button on the right-hand side of the integration designer. From the Endpoint Type input, select one of the three endpoint types listed above.

Select endpoint type in Prismatic app

Depending on what endpoint type you choose, you will be presented with different configuration options (described next).

Instance and Flow-Specific Endpoint Configuration#

This is the default configuration. When an instance is deployed to a customer, each flow within the instance is assigned its own webhook endpoint.

Customer A's "Update Inventory" flow has a unique endpoint that is different than Customer A's "Process Order" flow endpoint, and different than Customer B's "Update Inventory" flow endpoint.

Diagram of flow-specific endpoints

Integrations that use this endpoint configuration often set up webhooks with a deploy trigger, and remove them with an instance remove trigger.

Instance-Specific Endpoint Configuration#

When an instance is deployed to a customer, that instance is assigned a single webhook endpoint. The flows that comprise the instance all share that endpoint. Each customer's instance has a unique endpoint, so Customer A's instance of the "Acme ERP" integration will have one endpoint, and Customer B's instance of the same integration will have a different endpoint.

Diagram of instance-specific endpoints

If flows share an endpoint, which flow is executed? Since several flows share an endpoint URL, you need a way to determine which flow should run when data is sent to your endpoint. You can determine which flow to run in two ways:

  1. Without a preprocess flow. You can send the name of the flow that should run as an HTTP header or as a value in the HTTP payload.
  2. With a preprocess flow. You can designate one flow of your integration to be a preprocess flow - that flow will determine which sibling flow should run.

Instance-Specific Endpoint without a Preprocess Flow#

If you do not use a preprocess flow, you can send the name of the flow to run as an HTTP header or as a value in the HTTP payload.

Flow Name from HTTP Payload#

For example, you could send the name of the flow you'd like to execute as part of your payload like this:

Determine flow name from HTTP payload
curl https://hooks.prismatic.io/trigger/EXAMPLE== \  --location \  --header "Content-Type: application/json" \  --data '{"myFlowName":"Update Inventory","item":"widgets","quantity":5,"state":"removed"}'

Within the Endpoint Configuration drawer, you could choose to reference results.body.data.myFlowName to determine which flow to run:

Set flow name from HTTP payload for Endpoint Configuration in Prismatic app
/>

Given the curl invocation above, the Update Inventory flow would be run with the rest of the payload that was provided.

Flow Name from HTTP Header#

If you'd like to pass flow name as an HTTP header instead, a curl invocation could look like this:

Determine flow name from an HTTP header
curl https://hooks.prismatic.io/trigger/EXAMPLE== \  --location \  --header "Content-Type: application/json" \  --header "myflowname: Update Inventory" \  --data '{"item":"widgets","quantity":5,"state":"removed"}'

In that case, you would reference results.headers.myflowname to determine which flow to run:

Set flow name from HTTP header for Endpoint Configuration in Prismatic app
Use lower-case HTTP header keys

Per HTTP RFC 2616, HTTP headers should be case-insensitive. We've found HTTP clients to be inconsistent about their behavior and implementations, though. Postman, for example, will send camel-cased headers, while curl will always lower-case header keys.

We recommend that you use lower-case HTTP header keys to avoid compatibility issues.

Instance-Specific Endpoint with a Preprocess Flow#

If you need additional logic to determine which flow to run (for example, if you need to inspect an XML payload's shape to determine what kind of data was received), you can leverage a preprocess flow. This flow executes when data is sent to the instance's endpoint. It can be comprised of any number of steps, and the last step's results determine which sibling flow to execute.

To configure a preprocess flow, first build a flow that can inspect an incoming payload, and verify that the last step returns the name of the flow that you'd like to run next. Then, open the Endpoint Configuration drawer, select your preprocess flow from the Preprocess Flow dropdown menu, and under Flow Name select the key representing the name of the flow that should run:

Set flow name from preprocess flow for Endpoint Configuration in Prismatic app

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 and flow based on data contained in the HTTP request. Like Instance-Specific Endpoint Configuration, Shared Endpoint Configuration can be configured with or without a preprocess flow.

Diagram of shared endpoints

Shared Endpoint without a Preprocess Flow#

If you do not use a preprocess flow, the shared endpoint's webhook invocation must include an external customer ID and flow name either in the HTTP payload, or as HTTP headers. You can mix-and-match if you'd like - provide one value as an HTTP header and the other in the HTTP payload.

For example, if "Customer A" had an external ID of abc-123, and you wanted to invoke their Update Inventory flow, you could send this curl request with the flow name represented as an HTTP header, and customer ID represented in the HTTP payload:

Routing a request by header and payload
curl https://hooks.prismatic.io/trigger/EXAMPLE== \  --location \  --header "Content-Type: application/json" \  --header "myflowname: Update Inventory" \  --data '{"myCustomerId":"abc-123","item":"widgets","quantity":5,"state":"removed"}'
Set flow name from HTTP payload or header for shared endpoint configuration in Prismatic app
Flow name is not required for single-flow Integrations

If your integration is comprised of just a single flow, then you only need to specify an external customer ID and not a flow name.

Shared Endpoint with a Preprocess Flow#

If you need additional logic to determine which flow to run, or need to look up a customer's external ID, you should leverage a preprocess flow. This flow executes when data is sent to a shared endpoint. It can be comprised of any number of steps, and the last step's results determine which flow to execute for which customer. The final step must return an object containing both a external customer ID and a flow name.

Set flow name with preprocess flow for shared endpoint configuration in Prismatic app
Shared endpoint preprocess flows cannot reference config variables

When you use a shared endpoint, the preprocess flow runs without knowing yet what customer the data is destined for. It runs as a "system" instance, and is not bound to any particular customer.

Because of this, a preprocess flow cannot reference any customer-specific config variables or connections.

Shared Endpoint Config and Versioning#

An integration can have multiple versions, and customers' instance can be on different versions. The endpoint configuration can change between versions, but a shared endpoint exists outside of a specific instance.

So, which version's endpoint configuration is used? The answer is the latest version that is currently deployed to a customer.

If your integration currently has three available published versions: 4, 5 and 6, and some of your customers are on version 4 and some are on version 5, then the endpoint configuration on version 5 is used for the shared endpoint for all customers. If another instance is then deployed using version 6, then the endpoint configuration for version 6 is used for all customers. If that single instance of version 6 is removed, leaving just versions 4 and 5 deployed, the endpoint configuration for version 5 will be used for all customers.

Testing Endpoint Configuration#

You can test each of your flows individually (including a preprocess flow, if applicable) by clicking the SAVE & TEST FLOW button on the top right of the integration designer. If you would like to test your endpoint configuration, click the arrow icon to the right of SAVE & TEST FLOW, and toggle the dropdown to Test Endpoint Configuration. Then, you can click SAVE & TEST ENDPOINT to test your endpoint configuration.

To configure a test payload, open the TEST RUNNER drawer, select the Endpoint tab, and then select the Payload tab. You can enter the payload and any headers that you would like to send to the shared endpoint.

Test endpoint configuration in Prismatic app

Within the Logs and Step Outputs tabs you will see logs and step results for both the preprocess flow (if you have one), and the flow that the request was routed to.

Logs and step outputs for flows in Prismatic app

If an error is thrown (for example, the flow name that the preprocess flow generated was not found), that error will appear in the Logs tab.

Invocations from the integration designer are always dispatched to a test customer

The integration designer is a sandbox. No test invocations will go to your customers' instances.

Instead, if you use Shared Endpoint Configuration (where all customers' instances share an endpoint), the execution will always be dispatched to a "test customer" within the integration designer. So, you can reference any external customer ID and the endpoint configuration test will be routed to the "test customer."

Troubleshooting Shared Endpoints in Production#

If you have an integration with Instance-Specific Endpoint Configuration, then all logs and execution records will appear in the instance's execution results page. Executions that that run through a preprocess flow that then trigger a sibling flow are packaged together as one execution in the executions page. If your instance's preprocess flow throws an error or yields the name of a flow that doesn't exist, you can see those errors and step results from that page.

If you have an integration with Shared Endpoint Configuration, then the preprocess flow runs before it knows what customer it will dispatch the work to and is not tied to a specific instance.