API Endpoint

Overview

The API Endpoint trigger can be used to run Recipes by sending it an HTTP request or webhook. This option also allows passing data from the incoming request into the Recipe. For example, when a user uploads a document in your app, you could trigger a Recipe that sends a notification to your team as a Slack message in a chosen channel.

API Endpoint Recipes can also be used as a way to create actual endpoints that extend functionality on top of your API. For example, if you need custom logic to validate and deliver a welcome email to all new users that complete your app onboarding, you could build it in a Buildable Recipe with an API Endpoint trigger that can be called from the frontend of your onboarding application.

There are a few pieces about the API Endpoint Trigger that are important to familiarize yourself with:

The Endpoint URL

Your Recipe's unique URL can be found by clicking the Trigger step in your Recipe editor.

API Endpoint Recipes can be triggered by sending an HTTP request to their unique URL. By default, Recipes accept POST request types, as indicated by the request tag next to the Recipe's unique URL. Recipes accept GET request types, too.

Adding Input Parameters

To define the Recipe input parameters, manually enter the structure using the table in the drawer.

This table allows you to manually enter the expected parameters. Any data entered here as parameters can be used as variables by other steps in the Recipe. When you make a request to the Recipe, all input parameters are bundled into a single input parameter (i.e., query params and body params are accessed via $steps.trigger).

You can also choose to validate the incoming request data. For example, you can enforce that parameters should be required, that parameters should match an expected value, or that parameters should match an expected type. If the incoming request doesn't meet your Recipe's validation rules, the Recipe will automatically return a validation error response.

Providing an example Payload

When you add additional steps to your Recipe following the Trigger, it's easiest to do so when you have example data to pull from. To give yourself access to the data in later steps, simply define an example payload in this box.

Instant Authentication

Recipes come with optional out-of-the-box authentication. This feature is enabled/disabled via the toggle found below the Recipe's unique URL in the trigger drawer. Authentication is enabled on all newly created Recipes by default but can be manually disabled at any time.

When Authorization is enabled, calling the Recipe must be done while passing an Authorization Header, which will include your Authorization Token (or your app's users' Authorization Token). For example, if you are calling the Recipe from the browser using the fetch API, you'll pass the Authorization Header like this:

fetch("https://api.buildable.dev/trigger/v2/{{ YOUR_ENV }}-{{ YOUR_TRIGGER_ID}}", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer {{ YOUR_TOKEN }}"
},
"body": "{\"data\":\"Added new data\"}"
})
.then(response => {
console.log(response);
})
.catch(err => {
console.error(err);
});

To learn about how to pull your Authorization Token, visit the Authorization sections of our docs here:

Buildable's Authentication feature requires the Users Service

Buildable Authorization uses the Users Service behind the scenes. If you intend to leverage the power of the Instant Authorization feature, then you'll need to create a Users Service via the Services tab of your Buildable dashboard, which you can learn about in more detail in the section: