Endpoints are the basic building blocks of integrations in Integry. There are two directions of endpoints, which serve two distinct purposes:

Outgoing: An outgoing endpoint defines an HTTP request that Integry makes to an external API. Outgoing endpoints further have eight types, each for a different scenario. These types are mentioned below.

All the endpoint types mentioned above eventually send a request to an external API. Their inputs, outputs, and request structures differ from each other. While working with these, you can compose values of various fields using the Twig templating language, we will see this in detail later. The Twig objects and variables that are available to you are dictated by the context in which the endpoint will be used.

Incoming: An Incoming endpoint generates a URL on Integry where external API’s can send data. This endpoint is used in one context only which is:

Only trigger endpoints are of the Incoming type. When an event takes place in the third-party app and if we have subscribed to that event, this trigger endpoint notifies us. 

Creating an endpoint

Let us see how endpoints are actually created. The scope of this article covers the common steps you will encounter while creating most types of endpoints. The rest of the steps to be performed are discussed in respective endpoint articles.

There are two different ways of starting your endpoint creation. One is through the Create Endpoint button directly in the Endpoints tab of your app.

The other way is to add an endpoint through the activity creation screen. Like if you are creating an action, you will be asked for its endpoint in a drop-down field while configuring the action. From that drop-down, you can either select an existing endpoint in your app, or create a new one, as shown below.

In the second case, you will be creating your new endpoint in a popup window. However, the endpoint configuration is the same in both the above cases.

When you select Create Endpoint option from the Endpoints tab, the following form appears. 

After entering the endpoint name, you can do one of the two things:

1. Skip the Endpoint Type field and select an Endpoint Direction. Once you select Outgoing or Incoming, the form further expands with new fields. This will allow you to create the endpoint from scratch.

The details on how to fill all the newly generated fields will be discussed later.

2. Select an endpoint type from the dropdown. This will have all the above-mentioned endpoint types available in a dropdown as shown below.

Once you select an endpoint type, the form will expand further. But in this case, most of the newly generated fields will already be filled with generic data and you will only need to provide some specific info related to the variables in your case. This is also discussed later in the article.

Selecting the endpoint direction to create the endpoint

In the first case mentioned above, your form expands once you select an endpoint direction and this is what you see:

Let's see these fields in detail.

Request URL:

This has three parts which are explained below:

HTTP Verb

Select the HTTP verb or method that should be used to make this request. As of now, we support the following HTTP verbs but we can support more in the future. 

  • GET
  • POST
  • PUT
  • DELETE
  • ANY
  • PATCH

When you select the Incoming Endpoint type, we automatically select the ANY HTTP method. As we are receiving a request from a remote API whenever the subscribed event takes place. We cannot control the request method of the incoming request. 

URL

The field takes in the URL of the request. The URL you enter consists of two parts. The Base URL and the resource you want to point to. The Base URL you enter here is pre-defined at the time of app creation. They point to a server, which can be a staging server or production. You can run the endpoint in multiple environments. To learn more about Base URL, click here. The second part of the URL, where you specify the resource or any third-party URL can be constructed dynamically, using Twig syntax. If there are parts of the URL that should be dynamically replaced before making the request, you can specify them in the form of Twig template tags. We will see the URL field in each case later.

Request Template

If the HTTP Verb chosen by you supports Request body, you can compose that in this field. The structure of the request payload is specified in the third-party app documentation. For any dynamic values that vary from user to user, we create activity fields and use them via Twig. We have defined a Twig variable requestBody so that you can access all data you need in your request body and URL. requestBody is a pre-defined variable. Let us see a simple example below. 

We need to post a message to Basecamp. From Basecamp API Docs, we learn to post a message the following endpoint has to be called

POST /buckets/1/message_boards/3/messages.json

The URL above publishes a message in the project with ID 1 and under the message board with an ID of 3. Furthermore, we also know that the base part of this URL is https://3.basecampapi.com/5 where 5 is the Account ID.

The URL takes the account, project, and message board IDs whereas the request body carries the subject, status, and content of the message. We will define the following activity fields for this activity

The values of these fields will be accessed by concatenating the machine names of these fields to the requestBody variable. So the URL of the request will look like as shown below

https://3.basecampapi.com/{{requestBody.data.basecamp_account}}/buckets/{{requestBody.data.basecamp_project}}/message_boards/{{requestBody.data.basecamp_message_board}}/messages.json 

 Whereas the request payload will be formatted using the request template as shown below.

{
"subject": "{{ requestBody.data.basecamp_subject }}",
"status": "active",
"content": "{{ requestBody.data.basecamp_content }}"
}

The variables in the example above will be replaced by actual values and the request will be processed at the other end. 

Response Template 

By default, the response returned from remote API when executing the endpoint becomes the output of the endpoint itself. However, if you want to transform the response into a specific shape before returning it from the endpoint, then you can do so in the Response Template field. Here you have a twig variable available named response which contains the response returned from remote API. It could be an object or an array depending upon the structure of the remote response. You can pick stuff from it using Twig and compose a new JSON object in this field. 

Let us consider a simple example, we received access and refresh tokens when the user logged in. Now we want to save this response for later use. The response template will look like as shown below.

{
"access_token": "{{ response.access_token }}",
"refresh_token": "{{ response.refresh_token }}"
}

The values of the tokens are accessed using the response object. These values are saved in their respective variables. 

Sender Response Template

When you create an Incoming endpoint, the Response Template field is meant to transform the incoming request according to the requirements of templates in which the activity will be used. However, it is sometimes required to specify a response to be returned to the caller of the endpoint, in case of Incoming Endpoints. For that, you can click the Advanced Options button below the Response Template field to reveal the Sender Response Template field, as shown below.

In the Sender Response Template, you can specify a response to the external app that is sending you an incoming request (through webhooks). This is useful in specific scenarios like registering your app to receive further webhooks from an external app, etc.

Output Object

When creating the activity endpoint, you can specify the object expected as the activity output through Output Object. These objects are created by Integry, which are mostly generic such as, Contact, Task, User, Event, etc.
When you select the object you need to define the action to be performed on it in the Object Action field. Also, in the Object Output field you map the object's attributes to the parameters received in the payload. Learn, how to configure an output object. 

Tracking Property Name

This is the name of the property that is used to track the pointer till the last poll's processing. When we receive a remote response, we need to uniquely identify the objects in the array. It is relevant in the polling-based triggers. Some good candidates could be "id" of objects or the last_updated_timestamp.

When you are creating an Incoming type endpoint, you will view an option Show Advanced Options at the end of the page. These fields help us determine which event took place and which integration to run corresponding to that event, based on Integration ID or an Activity Field value.

Selecting the endpoint type to create the endpoint

In case you select an endpoint type, your endpoint direction will be selected by itself based on the endpoint type. Along with this, the rest of the fields in the expanded form will be auto-filled with twig syntax that is used in general in those fields.

Let's say you select an Action Endpoint from as the endpoint type. The endpoint direction will be selected to Outgoing and the expanded form will look like this:

As most of the actions use POST as the HTTP Verb, it is selected automatically here. All you need to provide will be the actual endpoint URL.

The Request Template is also auto-filled here with an example request payload with Basecamp API commands. You can just edit this payload according to API docs of your specific app for this endpoint.

From the auto-generated text, you can only edit the text that is in blue. If you want to edit the complete text, just click on the Convert to source code instead button below any template. This will change the text to source code view, which you can edit completely.

To revert back to the restricted text view, just click on the Reset code to preset button as seen above.

The Response Template and Header Details follow a similar pattern with auto-generated data. The text that is most commonly used in your specific endpoint type will be added to these fields. Learn in detail how to set up the action endpoint after selecting it as your endpoint type.

If you change your endpoint type while creating an endpoint, you will be asked for confirmation with the information that your work will be replaced. This is shown below.

Once you click continue, the endpoint fields and the data within them will change according to the new endpoint type. All the changed fields will be highlighted with a green border. This can also be seen in the action endpoint configuration image shown above in the article.

Testing Endpoints

You can test the endpoints you create, right away. To learn how to test an endpoint, click here

Following is a list of articles with details on how to create different endpoints after selecting their type.

Did this answer your question?