> For the complete documentation index, see [llms.txt](https://docs.fastn.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastn.ai/~/revisions/aj5eaS57qHvafrgYtfbL/fastn-v2/getting-started/your-first-integration.md).

# Your First Integration

This walkthrough takes you from an empty Fastn project to a working integration that your customers can use. You'll set up a connector, build a flow, create a tenant, embed a widget, and test the full loop.

**Time:** 20–30 minutes\
**Prerequisites:** A Fastn account with dashboard access. Familiarity with basic REST API concepts.

### What you'll build

A Slack notification flow. When an API request hits your flow endpoint, it sends a formatted message to a Slack channel. This is a simple, self-contained integration that demonstrates:

* Connecting a third-party app (Slack)
* Building a flow with a trigger and a connector step
* Testing the flow from the dashboard
* Embedding a widget so your customers can connect their own Slack workspace

We use Slack because it's easy to set up and the results are immediately visible. The same pattern applies to any connector — Shopify, HubSpot, Xero, or any other app in Fastn's library.

### Step 1: Add the Slack connector

1. In the Fastn dashboard, click **Connectors** in the left sidebar.
2. Click **Add Connector** (or the **+** button).
3. Search for **Slack** and select it.
4. You'll need to authenticate. Slack uses OAuth2 — click **Connect** and authorize Fastn to access your Slack workspace.
5. Once connected, you'll see Slack listed in your connectors with a green status.

> **📷 Screenshot needed:** Connectors page with the Add Connector button highlighted.

> **🎬 GIF needed:** Full Slack OAuth flow — clicking Connect, Slack authorization screen, redirect back to Fastn showing connected status.

> **📷 Screenshot needed:** Slack connector in the connectors list showing green connected status.

> **Tip:** This is your own Slack workspace for testing. When you embed the widget later, your customers will connect their own Slack workspaces — each stored as separate credentials under their tenant.

### Step 2: Create a flow

1. Click **Flows** in the left sidebar.
2. Click the **Create** button, then select **Flow**.
3. In the "Create a new Flow" dialog:
   * **Name:** `send_slack_notification` (only letters, numbers, and underscores — hyphens are not allowed)
   * **Trigger type:** Select **On API Request**
4. Click **Create**. The flow editor opens with your trigger step already on the canvas.

> **📷 Screenshot needed:** Create flow dialog showing the name field filled with `send_slack_notification` and the trigger type dropdown with "On API Request" selected.

> **📷 Screenshot needed:** Empty flow canvas with just the trigger step placed. Show the toolbar at the top (Test, Deploy, Integrate buttons).

> **Note:** If a welcome modal appears when the canvas loads, click **Skip** to dismiss it before adding steps.

### Step 3: Add a Slack step

1. Click the **+** button on the canvas (below the trigger step) to open the step picker.
2. Click the **Connection** tab.
3. Select **Connector**.
4. In the connector configuration panel:
   * **Connector:** Select **Slack**
   * **Action:** Select **Send Message** (or the equivalent messaging action)
   * **Channel:** Enter a Slack channel name (e.g., `#general` or `#test`)
   * **Message:** Enter a test message, e.g., `Hello from Fastn! This is my first integration.`
5. The message field supports dynamic data. To use data from the trigger (the incoming API request), use the mapping syntax: `{{input.message}}`. This pulls the `message` field from the request body.

> **🎬 GIF needed:** Opening the step picker by clicking +, selecting the Connection tab, choosing Connector, and seeing the configuration panel appear.

> **📷 Screenshot needed:** Connector step configuration panel with Slack selected, Action set to Send Message, Channel and Message fields filled in. Show the `{{input.message}}` syntax in the Message field.

> **Important:** If you use `{{input.message}}` or any input mapping, you need to define sample input data before testing. See Step 4.

### Step 4: Test the flow

Before deploying, test the flow from the editor to make sure it works.

1. Click the **Test** button in the top-right toolbar of the flow editor.
2. The Terminal panel opens at the bottom of the canvas.
3. Click the **Input** tab in the Terminal panel.
4. Enter sample JSON data that your flow expects:

```json
{
  "message": "Test notification from Fastn"
}
```

5. Click **Run** (or **Send**) to execute the test.
6. Check the **Output** tab to see the response. A successful execution returns a 200 status.
7. Check your Slack channel — you should see the message appear.

> **📷 Screenshot needed:** Terminal panel open at the bottom of the canvas, Input tab selected, showing the sample JSON `{"message": "Test notification from Fastn"}`.

> **📷 Screenshot needed:** Output tab in the Terminal panel showing a successful 200 response after test execution.

> **📷 Screenshot needed:** Slack channel (#general or #test) showing the received test message from Fastn.

> **Common issue:** If the output shows an empty value for `{{input.message}}`, make sure you've entered the sample input data in the Terminal's Input tab. Without sample data, the mapping resolves to empty during testing.

### Step 5: Deploy the flow

Testing doesn't deploy. Your flow is still in "Changes Pending" status. To make it live:

1. Click the **Deploy** button in the top-right toolbar.
2. The flow status changes from **Changes Pending** to **Live**.
3. Your flow now has a live endpoint. Find the URL by clicking **Integrate** (the `</>` button) in the toolbar.

The endpoint URL follows this pattern:

```
https://live.fastn.ai/app/projects/{your-project-id}/api/send_slack_notification
```

You can now send API requests to this endpoint, and the flow will execute. Each request needs these headers:

| Header             | Value                              |
| ------------------ | ---------------------------------- |
| `x-fastn-api-key`  | Your API key (Settings → API Keys) |
| `x-fastn-space-id` | Your Project ID                    |
| `Content-Type`     | `application/json`                 |

Example cURL:

```bash
curl -X POST \
  https://live.fastn.ai/app/projects/{your-project-id}/api/send_slack_notification \
  -H "x-fastn-api-key: YOUR_API_KEY" \
  -H "x-fastn-space-id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from my integration!"}'
```

> **📷 Screenshot needed:** Flow editor toolbar showing the Deploy button and the Live status badge (green) after deployment.

> **📷 Screenshot needed:** Integrate panel (opened via the `</>` button) showing the flow's endpoint URL and the required headers.

### Step 6: Create a test tenant

Your flow works for you, but in production it needs to work for your customers. Each customer is a **tenant** with their own credentials and data.

1. Go to **Settings → Tenants** in the sidebar.
2. Click **Add Tenant** (or **Create Tenant**).
3. Enter a name for your test tenant (e.g., "Acme Corp Test").
4. Note the **Tenant ID** — you'll use this in API calls via the `x-fastn-space-tenantid` header.

When you make API calls on behalf of a tenant, include the tenant ID header:

```bash
curl -X POST \
  https://live.fastn.ai/app/projects/{your-project-id}/api/send_slack_notification \
  -H "x-fastn-api-key: YOUR_API_KEY" \
  -H "x-fastn-space-id: YOUR_PROJECT_ID" \
  -H "x-fastn-space-tenantid: TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from Acme Corp!"}'
```

> **📷 Screenshot needed:** Settings → Tenants page showing the tenant creation form with a name field.

> **📷 Screenshot needed:** Tenant list after creation, showing the new tenant name and its Tenant ID value.

### Step 7: Embed a widget

Now give your customers a way to connect their own Slack workspace through your product.

1. Go to **Widgets** in the left sidebar.
2. Click **Create** and select **Widgets Starter** (or the appropriate template).
3. In the widget editor:
   * Add the Slack connector as an available integration
   * Link the `send_slack_notification` flow to the widget's actions (do this in the widget editor's **Actions** section)
   * Customize the branding to match your product
4. Click **Save**.

To embed the widget in your frontend, use the embed code from the widget's **Integrate** panel. The panel provides a ready-to-use code snippet with your Project ID and configuration options pre-filled.

> ⚠️ **VERIFY:** The exact widget embed API (script URL, init method name, parameter names) needs to be confirmed on live.fastn.ai. Copy the actual snippet from the Integrate panel before publishing.

When your customer loads this page, they see the widget, click "Connect Slack," go through the OAuth flow with their own Slack workspace, and Fastn stores their credentials separately from yours.

> **📷 Screenshot needed:** Widget editor showing the Actions section where the `send_slack_notification` flow is linked to the widget.

> **🎬 GIF needed:** Full widget embed experience from the end user's perspective — opening the widget inside a sample app, clicking "Connect Slack", completing OAuth, seeing the connected state.

> **📷 Screenshot needed:** The embedded widget as it appears inside a sample SaaS product, showing connected integrations and status.

### Step 8: Verify in Logs

After a flow executes, check the results:

1. Go to **Logs** in the left sidebar.
2. You'll see a list of recent executions. Each row shows:
   * **Flow Name** — which flow ran
   * **Request Time** — when it was triggered
   * **Duration** — how long it took
   * **HTTP Status Code** — 200 for success, 4xx/5xx for errors
   * **Tenant ID** — which customer's execution this was
3. Click on an execution to see step-level details, including input/output data for each step and any error messages.

> **📷 Screenshot needed:** Logs page showing a list of recent executions with all columns visible — Flow Name, Request Time, Duration, HTTP Status Code, Tenant ID.

> **📷 Screenshot needed:** Execution detail view after clicking a row — showing the step-level breakdown with input/output data per step and any error messages.

### What you've built

In this walkthrough, you:

1. Connected a third-party app (Slack) to your Fastn project
2. Built an automation flow that sends Slack messages when triggered via API
3. Tested and deployed the flow
4. Created a tenant to represent one of your customers
5. Set up a widget so your customers can connect their own Slack workspace
6. Verified execution in the Logs

This is the core pattern for every integration on Fastn: **Connector → Flow → Widget → Tenant isolation**. The same workflow applies whether you're syncing Shopify orders to Xero, pushing HubSpot contacts to your database, or pulling GitHub issues into your project management tool.

### Next steps

Now that you have a working integration, explore these areas:

* [**Flow Setup Essentials**](https://claude.ai/flows/flow-setup-essentials.md) — Deeper dive into flow components, triggers, and configuration
* [**Embedded Integrations**](https://claude.ai/embedded-integrations/embedded-integrations.md) — Advanced widget customization and embedding patterns
* [**UCL / MCP Server**](https://claude.ai/ai-agent-integrations-ucl/getting-started.md) — Connect AI agents to your integrations
* [**Tutorials**](https://claude.ai/flows/tutorials/) — Step-by-step guides for specific integration patterns (OAuth, error handling, data migrations, pagination)

***

> **Feedback:** If any step in this walkthrough didn't match what you see in the platform, let us know. File an issue at [github.com/fastnai/docs](https://github.com/fastnai/docs) or reach out to the Fastn team directly.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fastn.ai/~/revisions/aj5eaS57qHvafrgYtfbL/fastn-v2/getting-started/your-first-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.