Building a basic webhook flow

In this article we will cover how to create an integration flow that gets triggered by a webhook.

We will create an integration flow that exposes an externally-reachable URL to accept HTTP requests in JSON format. The received payload gets interpreted as a pet and gets stored into the Petstore API.

Setting up the webhook trigger

The first step in every flow is a trigger which starts the flow by causing data to be input into the flow from an external system. In this case we are using a webhook to retrieve data so the trigger component will be the generic webhook. This component can be used to retrieve data from any external application that supports webhooks.

  • Click the "Add new flow" button on the Dashboard or on the Flows page to open the Flow designer page and start building your flow.

Start creating your flow
  • Click "Add the initial trigger".

  • The page that displays lists all of the components that can be used as a trigger. Scroll through them or use the search bar (1) to find the Webhook component.

  • Click the component to select it and then click "Choose Webhook" (2).

Selecting the webhook component

The next thing you need to do is set up credentials for the webhook you want to use.

Add credentials
  • If you have entered these already on the Credentials page they will be available for selection in a searchable list

  • If you have credentials to enter or want to proceed without credentials click "Add New Credential"

    • Enter a name for your credential

    • Select the type of authentication the sender application requires and populate the required fields, or choose "No Auth" to proceed without authentication.

    • Select the credential you added

For this example we will proceed using "No Auth".

  • Click "Save" to proceed.

Note: When you add credentials to a component, they are available within the workspace you are working in only. However a component may have multiple credentials associated with it. In particular generic components like webhooks may have credentials for multiple external applications and multiple environments. Use meaningful credential names to ensure you and your team select the right credentials for each flow.

Types of credentials

Note: As you can see in the image above some of the configuration steps were completed automatically for you. This will happen for most components. You can go back and review these tabs but you will rarely need to change these default settings.

In the Sample tab we need to define the sample data structure that the webhook expects to receive from the external system. You can choose to "Add sample manually" or "Send sample request" to add your sample.

Add sample manually

In this case we will manually input a sample. The sample must be a valid `JSON`object

  • Click "Add sample manually".

You now have the option to * Enter a JSON object into the input field. In this case, paste the following JSON in the input field. * Click Generate Stub Sample to generate a correctly formatted JSON object and edit it as needed.

{
  "petname": "Gromit",
  "petstatus": "sold"
}

The sample is evaluated (1). If it is valid, you can click Save (2).

Paste the JSON

We have now the sample data for our webhook.

  • Click the "Continue" button to finish configuring the webhook component and load the step summary page.

Webhook step summary

The screenshot above shows the Webhook step summary page.

  • Optionally edit the step Name and Description.

  • Click "Finish step" to finish this Webhook step and return to the Flow Designer.

Choosing the data receiver

After you have a trigger configured to bring data into the flow, you need to configure actions that might transform the data, use it, or send it to another application. In this case we want to send the data to the component Petstore API (Node.js)

  • Click "Add a new action_"

  • Use the search field to find the Petstore API component and select it

  • Click "Choose Petstore API"

Choose Petstore component

A typical platform component will have multiple available actions to retrieve, change or add records at the target API. In this example there are two actions to select from.

  • Select "Create a Pet With Generators" and continue.

Select action

You are now required to select or enter credentials for the Petstore API. This is similar to adding credentials to the Webhook component but simpler - Petstore API is not a generic component so the Credential Type is selected for you and cannot be changed.

  • Add new credential details as follows and click Save to verify the credentials.

    • Account name: Enter a meaningful name for your credential

    • API key: secret

Create credentials to access

The fields on the Input tab represent the fields on the Receiver (Petstore) application that may be populated. In this step we need to choose what incoming data from the webhook matches each of the Petstore fields. The asterisks indicate that they are both mandatory.

  • Click in the "Name" field and expand the sections in the dropdown to find the available fields under the Webhook component.

  • Select petname

  • Repeat the process for the "Status" field and select petstatus

  • Click "Continue"

Mapping the values

We are now required to populate a sample of the data that will be the output for this step. We are authenticated with the Petstore API so we can retrieve this sample automatically.

  • Click Retrieve sample from Petstore API (Node.js) to retrieve the sample.

You can see that the sample represents the input JSON sample from the webhook, mapped according to the rules in the Input set for the Petstore.

  • Click "Choose this sample" to continue.

Retrieve the sample

You can now review your configuration summary, optionally update the name and description and click "Finish Step"

Petstore step summary

On the Flow Designer page click "Publish Draft" to make your draft live.

Publish the draft

© 2015- Squiz Pty Ltd