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

# n8n Integration

> Use the Sequenzy community node to trigger n8n workflows from Sequenzy events, add subscribers, manage tags, and send events from n8n workflows.

# n8n Integration

Use the Sequenzy community node for n8n to trigger workflows from Sequenzy
outbound events, and to send form submissions, billing events, spreadsheet
rows, and other workflow data into Sequenzy.

The package is published as
[`n8n-nodes-sequenzy`](https://www.npmjs.com/package/n8n-nodes-sequenzy). The
source is available on
[GitHub](https://github.com/Sequenzy/n8n-nodes-sequenzy).

## Install the Community Node

Install Sequenzy from n8n's Community Nodes screen:

1. In n8n, go to **Settings > Community Nodes**.
2. Select **Install**.
3. Enter `n8n-nodes-sequenzy`.
4. Confirm the install and restart n8n if your instance asks you to.
5. Add a **Sequenzy** node to a workflow.

For self-hosted deployments, you can also install the package with npm in the
n8n environment:

```bash theme={null}
npm install n8n-nodes-sequenzy
```

<Warning>
  Install community nodes only in n8n workspaces where your team allows
  community packages. Sequenzy does not require any manual approval outside your
  n8n instance.
</Warning>

## Authentication

The n8n node uses Sequenzy API key authentication.

1. In Sequenzy, go to **Settings > API Keys**.
2. Create or copy a workspace API key. New workspace keys start with
   `seq_live_`; legacy `ek_` keys remain supported.
3. In n8n, create a credential of type **Sequenzy API**.
4. Paste the API key and save the credential.
5. Select that credential on each Sequenzy node.

By default, the credential sends requests to
`https://api.sequenzy.com/api/v1` with:

```txt theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Supported Operations

The package includes a trigger node and an action node.

| Node             | Resource/Operation          | What it does                                                                |
| ---------------- | --------------------------- | --------------------------------------------------------------------------- |
| Sequenzy Trigger | Events                      | Starts a workflow from selected Sequenzy outbound webhook events            |
| Sequenzy         | Subscriber/Create or Update | Creates or updates a subscriber by email or external ID                     |
| Sequenzy         | Subscriber/Get              | Looks up a subscriber by email or external ID                               |
| Sequenzy         | Subscriber/Delete           | Deletes a subscriber by email or external ID                                |
| Sequenzy         | Tag/Add                     | Adds a tag to a subscriber, creating the subscriber if needed               |
| Sequenzy         | Tag/Remove                  | Removes a tag from a subscriber                                             |
| Sequenzy         | Event/Trigger               | Triggers a custom event for a subscriber, creating the subscriber if needed |

### Trigger Events

Use **Sequenzy Trigger** when Sequenzy should start an n8n workflow. Choose one
or more outbound events; the default is **New Subscriber**
(`subscriber.created`). The trigger creates an ordinary Sequenzy outbound
webhook endpoint using n8n's production webhook URL, stores the one-time HMAC
signing secret in the workflow's node static data, and verifies
`X-Sequenzy-Signature` before starting the workflow.

Common trigger events:

* `subscriber.created` for new subscribers
* `campaign.sent` when an email or SMS campaign reaches its final sent state
* `email.replied` for inbound replies
* `subscriber.unsubscribed` for opt-outs
* `sequence.finished` and `sequence.failed` for lifecycle automation

The trigger outputs the full Sequenzy event envelope, including `id`, `type`,
`created_at`, `metric`, and `data`.

Delivery uses the same durable outbound-webhook pipeline as every other
Sequenzy endpoint: each request is HMAC-signed and failed deliveries are tried
up to 16 times across seven days. Per-message events such as `email.opened`,
`email.clicked`, and `email.sent` can start one n8n execution per recipient, so
select them only when the workflow is sized for that volume.

### Subscriber Fields

Create or Update supports:

* Email or External ID
* First name
* Last name
* Tags as a comma-separated list
* Custom attributes as key-value pairs
* Enroll in Sequences

Get and Delete accept either Email or External ID.

### Tag Fields

Add and Remove require a tag plus either Email or External ID. Add also accepts
first and last name values for cases where Sequenzy needs to create the
subscriber before applying the tag.

### Event Fields

Trigger requires an event name plus either Email or External ID. You can also
send first name, last name, and event properties as key-value pairs.

Use event names that match your Sequenzy automations, such as
`signup.completed`, `trial_started`, `checkout.completed`, or
`subscription.canceled`.

## Example Workflows

### Webhook or Form to Sequenzy Subscriber

Use this when a custom form, landing page, or internal app can POST to n8n.

```txt theme={null}
Webhook/Form Trigger -> Set -> Sequenzy: Subscriber Create or Update
```

Map the incoming email to the Sequenzy Email field. Put form answers you want to
segment on into Custom Attributes, and add tags such as `lead`, `demo-request`,
or `newsletter`.

### Typeform, Tally, or Jotform to Sequenzy Subscriber

Use the native app node when your n8n instance has one, or use the app's webhook
feature with n8n's Webhook node.

```txt theme={null}
Typeform/Tally/Jotform -> Set -> Sequenzy: Subscriber Create or Update
```

Recommended mapping:

| Form value                 | Sequenzy field          |
| -------------------------- | ----------------------- |
| Email question             | Email                   |
| Name question              | First Name or Last Name |
| Hidden user/customer ID    | External ID             |
| Plan, company size, source | Custom Attributes       |
| Form name or intent        | Tags                    |

### Stripe Event to Sequenzy Event

Use this when payment activity should trigger Sequenzy automations.

```txt theme={null}
Stripe Trigger/Webhook -> Set -> Sequenzy: Event Trigger
```

Recommended events:

* `stripe.checkout_completed`
* `stripe.subscription_created`
* `stripe.payment_failed`
* `stripe.subscription_canceled`

Map the customer email or your own customer ID, then pass Stripe values such as
price ID, product name, subscription status, amount, currency, or trial end as
event properties.

### Google Sheets Row to Sequenzy Subscriber

Use this when a spreadsheet is the source of leads or imported contacts.

```txt theme={null}
Google Sheets Trigger/Read Rows -> Sequenzy: Subscriber Create or Update
```

Map the email column to Email. Map name columns to First Name and Last Name. Map
other columns such as company, role, plan, or source to Custom Attributes.

### Sequenzy Event to n8n Workflow

Use this when Sequenzy should notify n8n about email, campaign, subscriber, or
sequence lifecycle events.

```txt theme={null}
Sequenzy Trigger -> Switch/Set -> Any n8n action
```

Add a **Sequenzy Trigger** node, select your **Sequenzy API** credential, and
choose the events your workflow needs. n8n must provide a production HTTPS
webhook URL when the workflow is activated. The API key must have account read
and webhook read, write, and delete permissions (`account:read`,
`webhooks:read`, `webhooks:write`, and `webhooks:delete`). Account read lets n8n
validate the shared Sequenzy credential; the webhook permissions let the node
create, reconcile, and clean up its managed outbound webhook endpoint.

### Manual Fallback: Sequenzy Outbound Webhook to n8n Webhook Node

Use this if you prefer n8n's generic Webhook node or cannot install community
trigger nodes.

```txt theme={null}
Sequenzy Outbound Webhook -> n8n Webhook -> Switch/Set -> Any n8n action
```

Create an n8n **Webhook** node first and copy its production URL. Then create a
Sequenzy outbound webhook endpoint pointing to that URL. Subscribe to the
Sequenzy events your workflow needs, such as `campaign.sent`, `email.replied`,
`subscriber.unsubscribed`, `sequence.finished`, or `email.clicked`.

See [Outbound Webhooks](/integrations/outbound-webhooks) for payloads,
signatures, retries, and delivery behavior.

## Limitations

* The Sequenzy Trigger manages one Sequenzy outbound webhook endpoint per
  active workflow. Deactivating the workflow deletes that managed endpoint.
* The node uses API key authentication. OAuth is not supported.
* The node runs once per incoming n8n item. For high-volume imports, prefer the
  Sequenzy bulk API endpoints or batch your workflow carefully.
* Custom attributes and event properties are configured as key-value pairs in
  the node UI. Use a Set or Code node before Sequenzy if you need to normalize
  complex source data.
* Subscriber lookup returns data only when a matching subscriber is found. Build
  your workflow so the not-found path is handled explicitly.

## Troubleshooting

### Test Against a Local Sequenzy API

The node uses `https://api.sequenzy.com/api/v1` by default. When developing the
node locally, start n8n with `SEQUENZY_API_BASE_URL` set to the local API:

```bash theme={null}
SEQUENZY_API_BASE_URL=http://127.0.0.1:4000/api/v1 npm run dev
```

Restart n8n after changing the value. If the variable is unset or blank, the
node uses the production Sequenzy API. This override is for local or self-hosted
n8n because n8n Cloud does not expose custom environment variables to community
nodes.

To test the trigger locally, expose n8n's port with ngrok:

```bash theme={null}
brew install ngrok
ngrok config add-authtoken YOUR_NGROK_AUTHTOKEN
ngrok http 5678
```

Keep ngrok running, copy its HTTPS forwarding URL, and restart n8n:

```bash theme={null}
SEQUENZY_API_BASE_URL=http://127.0.0.1:4000/api/v1 \
N8N_WEBHOOK_URL=https://YOUR-NGROK-DOMAIN.ngrok.app/ \
N8N_PROXY_HOPS=1 \
npm run dev
```

### Credential Test Fails

Confirm the workspace API key starts with `seq_live_` (or the legacy `ek_`
prefix), has not been deleted, and was pasted into the **Sequenzy API**
credential without extra spaces.

### Subscriber Was Not Created

Confirm the workflow provides either Email or External ID. For new subscribers,
Email is recommended because Sequenzy needs an address before it can send email.

### Automation Did Not Start

Confirm the Sequenzy automation is published and listens for the exact event
name or tag used by the n8n node. Event names and tag names are case-sensitive.

### Outbound Webhook Did Not Reach n8n

For **Sequenzy Trigger**, confirm the workflow is active, n8n exposes a public
HTTPS production URL, and the credential has account read plus webhook read,
write, and delete permissions. Deactivate and reactivate the workflow to
recreate an endpoint whose one-time signing secret is missing. Then check
webhook delivery status in Sequenzy and execution history in n8n.

For the manual fallback, use the production URL from the n8n Webhook node, not
its temporary test URL.

## Resources

* [n8n package on npm](https://www.npmjs.com/package/n8n-nodes-sequenzy)
* [Sequenzy n8n node on GitHub](https://github.com/Sequenzy/n8n-nodes-sequenzy)
* [n8n Community Nodes documentation](https://docs.n8n.io/integrations/community-nodes/installation/)
* [Sequenzy API Reference](/api-reference)
* [Outbound Webhooks](/integrations/outbound-webhooks)