> ## Documentation Index
> Fetch the complete documentation index at: https://docs.feedal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How integrations work

> Events, delivery, retry logic, and the integration status model — everything you need to know before setting up your first integration.

Integrations connect your forms to external tools. When something happens on a form — a respondent starts or completes a session — Feedal fires an **event** and delivers a payload to every connected integration.

***

## Concepts

### Integration vs form integration

There are two layers:

* **Integration** — an account-level connection to a service (e.g. "My Slack workspace"). Created once, reusable across forms.
* **Form integration** — attaches an integration to a specific form and controls which events trigger it. One integration can be attached to multiple forms.

### Events

Two events are currently supported:

| Event               | Fires when                                           |
| ------------------- | ---------------------------------------------------- |
| `session.completed` | A respondent reaches an End screen and submits       |
| `session.started`   | A respondent opens the form and a session is created |

Each form integration has an **events** list. You choose which events trigger a delivery for that form.

### Payload

Every delivery sends a JSON payload with the same structure regardless of integration type:

```json theme={null}
{
  "event": "session.completed",
  "feedal_version": "2.0",
  "form": {
    "id": "uuid",
    "slug": "your-form-slug",
    "title": "Customer feedback"
  },
  "session": {
    "id": "uuid",
    "started_at": "2026-03-17T10:00:00Z",
    "completed_at": "2026-03-17T10:03:24Z",
    "duration_seconds": 204,
    "total_score": 42,
    "answers": {
      "node_abc123": "Very satisfied",
      "node_def456": 9
    }
  },
  "timestamp": "2026-03-17T10:03:24Z"
}
```

The `answers` object maps each question node ID to the respondent's raw answer value. Complex answers (arrays, objects) are serialised to JSON strings.

***

## Setting up an integration

<Steps>
  <Step title="Create an account-level integration">
    Go to **Integrations** in the main sidebar. Click **New integration**, choose a type, fill in the configuration, and save.

    For OAuth integrations (HubSpot, Pipedrive, Google Sheets), click **Connect** and complete the authorisation flow.
  </Step>

  <Step title="Attach to a form">
    Open a form and go to the **Connect** tab in the studio. Find the integration you want to attach and click **Connect**.

    Choose which events should trigger a delivery for this form.
  </Step>

  <Step title="Test the connection">
    Click **Test** on any form integration to fire a test delivery immediately. The delivery log shows the result within seconds.
  </Step>
</Steps>

***

## Delivery log

Every delivery attempt — success or failure — is recorded in the **delivery log**. Access it from the **Connect** tab or from the Integrations page.

Each log entry shows:

| Field             | Description                                |
| ----------------- | ------------------------------------------ |
| **Event**         | Which event triggered the delivery         |
| **Status**        | `success` or `error`                       |
| **Response code** | HTTP status code returned (e.g. 200, 500)  |
| **Duration**      | How long the delivery took in milliseconds |
| **Timestamp**     | When the delivery was attempted            |

### Retry

Failed deliveries can be retried manually. Click **Retry** on any failed log entry. A fresh delivery is queued immediately with the same payload.

***

## Integration statuses

| Status     | Meaning                                      |
| ---------- | -------------------------------------------- |
| `active`   | Integration is connected and delivering      |
| `inactive` | Integration is disabled (no deliveries sent) |
| `error`    | Last delivery failed; check the log          |
| `pending`  | Integration created but not yet tested       |

***

## Failure notifications

Each form integration has a **Notify on failure** toggle. When enabled, Feedal sends you an email alert if consecutive delivery failures exceed a threshold. The counter resets automatically on the next successful delivery.

***

## Security

* **OAuth integrations** (HubSpot, Pipedrive, Google Sheets) store access tokens encrypted at rest. Tokens are refreshed automatically before they expire.
* **Secret fields** (API keys, auth tokens) are always masked in the UI and API responses — they are never returned in plain text after saving.
* **Webhooks** include an `X-Feedal-Signature` header for payload verification. See [Webhooks](/integrations/webhook) for details.

***

## Available integrations

<CardGroup cols={3}>
  <Card title="Webhook" icon="webhook" href="/integrations/webhook">Developer</Card>
  <Card title="Email notification" icon="envelope" href="/integrations/email">Notification</Card>
  <Card title="Slack" icon="slack" href="/integrations/slack">Messaging</Card>
  <Card title="Zapier" icon="zap" href="/integrations/zapier">Automation</Card>
  <Card title="Make" icon="settings" href="/integrations/make">Automation</Card>
  <Card title="HubSpot" icon="building-2" href="/integrations/hubspot">CRM</Card>
  <Card title="Pipedrive" icon="building-2" href="/integrations/pipedrive">CRM</Card>
  <Card title="Google Sheets" icon="file-spreadsheet" href="/integrations/google-sheets">Spreadsheet</Card>
  <Card title="Airtable" icon="database" href="/integrations/airtable">Spreadsheet</Card>
  <Card title="Notion" icon="database" href="/integrations/notion">Spreadsheet</Card>
</CardGroup>