Endpoints are the basic building block of integrations in Integry. There are two types of endpoints and they serve two distinct purposes:

Outgoing: An Outgoing endpoint defines an HTTP request that Integry makes to an external API. This endpoint is used in five different scenarios, all these scenarios are mentioned below

  • Action Endpoint
  • Hooks in an action or trigger
  • Source of a Dynamic Activity Field
  • Fields List Source Enpoint
  • Access Token Endpoint in an authorization
  • User Information Endpoint in an authorization
  • Polling based Trigger Endpoint

All the endpoints types mentioned above eventually send a request to an external API. Their inputs, outputs, request structure 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:

  • Webhook based Trigger Endpoint

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, trigger endpoint notifies us. 

How to create an Endpoint?

Let us see how endpoints are actually created. The scope of this article covers the common steps you will encounter while creating both types of endpoints. The rest of the steps to be performed are discussed in respective endpoint’s articles. No matter, you are creating an Incoming or an Outgoing endpoint, when you select Create new endpoint option the following form appears in both cases. 

Enter the endpoint Name and select the Endpoint Type. When you select the endpoint type, the form further expands as shown below.

Let us see these fields in detail.

Request URL: It has two 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

When you select the Incoming Endpoint type, we automatically select 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. It supports Twig syntax, so 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_message_subject }}",
"status": "active",
"content": "{{ requestBody.data.basecamp_message_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 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. 

Tracking Property Name

This is the name of the property that is used to track the pointer till 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.

Integration Mapping

This is an additional field to be configured for trigger endpoints. This field helps us determine which event took place and which integration to run corresponding to that event. We will dig deeper into this when we discuss trigger endpoints in detail. 

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 on how to create different endpoints

Did this answer your question?