n8n-nodes-arrivy

Custom n8n node package for integrating Arrivy — a field service management platform — with n8n workflows.

---

What's Included

File	Style	Purpose
ArrivyOAuth2Api.credentials.ts	—	OAuth2 credential definition
ArrivyTrigger.node.ts	Programmatic	Webhook trigger — listens for Arrivy events
Arrivy.node.ts	Mixed	Actions — Create Task (programmatic), Get Task by ID (declarative)

---

Architecture Overview

Arrivy Platform
     │
     │  (fires event e.g. customer_created)
     ▼
n8n Webhook URL  ──→  ArrivyTrigger node  ──→  Your workflow
                            │
                    (registered via subscribe API on workflow activation)

User fills n8n form  ──→  Arrivy node (Create Task)  ──→  POST /api/tasks/new  ──→  Arrivy
User fills n8n form  ──→  Arrivy node (Get Task)     ──→  GET /api/tasks/:id   ──→  Arrivy

---

Authentication Flow (OAuth2)

No refresh token is implemented — matching the existing Zapier integration.

1. User clicks "Connect Arrivy Account" in n8n
        │
        ▼
2. n8n redirects user to:
   https://app.arrivy.com/oauth2/consent?integration_type=n8n
   &client_id=<YOUR_CLIENT_ID>
   &redirect_uri=<n8n_callback_url>
   &response_type=code
   &scope=profile
        │
        ▼
3. User approves → Arrivy redirects back with ?code=<auth_code>
        │
        ▼
4. n8n POSTs to https://app.arrivy.com/api/oauth2/access_token
   Body (form-encoded):
     client_id=<YOUR_CLIENT_ID>
     client_secret=<YOUR_CLIENT_SECRET>
     grant_type=authorization_code
     code=<auth_code>
     scope=profile
        │
        ▼
5. Arrivy responds: { "access_token": "..." }
        │
        ▼
6. n8n stores access_token securely in the credential
        │
        ▼
7. Every subsequent API request automatically gets:
   Authorization: Bearer <access_token>

---

Trigger Flow (Customer Created / Webhook)

User adds ArrivyTrigger node → selects event = "customer_created"
        │
        ▼
User activates workflow
        │
        ▼
n8n calls webhookMethods.default.create()
  → POSTs to /api/external_integrations/n8n/hooks/subscribe
    Body: { target_url: "<n8n webhook URL>", event: "customer_created" }
  → Arrivy responds: { "id": "<hookId>" }
  → n8n stores hookId in workflow static data
        │
        ▼
Arrivy fires a customer_created event
  → POSTs payload to n8n webhook URL
  → n8n calls webhook() handler
  → Raw JSON body passed downstream to next node
        │
        ▼
User deactivates workflow
  → n8n calls webhookMethods.default.delete()
  → DELETEs /api/external_integrations/n8n/hooks/unsubscribe/<hookId>
  → Arrivy stops sending events

---

Action Flow (Create Task)

Previous node output → Arrivy node (operation: Create Task)
        │
        ▼
User fills in: title, customer fields, datetime, notifications, etc.
        │
        ▼
execute() runs:
  → Builds notifications object: { sms: true, email: true } (adjusted per user choice)
  → Builds task payload (field names match Arrivy API exactly)
  → JSON.stringifies notifications
  → Removes empty fields (Arrivy interprets blank as intentional clear)
  → POSTs form-encoded body to /api/tasks/new
  → Authorization: Bearer <token> injected automatically
        │
        ▼
Arrivy creates the task → responds with created task object
        │
        ▼
Task data passed to next node

---

Action Flow (Get Task by ID) — Declarative

Previous node output → Arrivy node (operation: Get Task by ID)
        │
        ▼
User provides: taskId
        │
        ▼
n8n reads the routing config from the node description (declarative)
  → Builds: GET https://app.arrivy.com/api/tasks/<taskId>
  → Authorization: Bearer <token> injected automatically
  → No execute() code runs — n8n handles it entirely
        │
        ▼
Arrivy responds with task object → passed to next node

---

Prerequisites

• Node.js 18+
• npm 8+
• A running n8n instance (local or cloud)
• Arrivy OAuth2 credentials: client_id and client_secret
  (request from Arrivy if you don't have them)

---

Setup & Running

Step 1 — Clone and install

git clone <this-repo>
cd n8n-nodes-arrivy
npm install

Step 2 — Build

Compiles TypeScript → JavaScript in dist/, and copies SVG icons.

npm run build

You should see a dist/ folder with:

dist/
  credentials/
    ArrivyOAuth2Api.credentials.js
  nodes/
    Arrivy/
      Arrivy.node.js
      ArrivyTrigger.node.js
      arrivy.svg

Step 3 — Link the package to your local n8n

n8n loads custom nodes from a special folder. The easiest way during development is npm link.

# In this repo folder:
npm link

# Then in your n8n folder (or wherever n8n is installed):
npm link n8n-nodes-arrivy

Alternatively, copy the entire package into n8n's custom extensions folder:

~/.n8n/custom/   ← put the package here

Step 4 — Start n8n

n8n start

Open http://localhost:5678 in your browser.

Step 5 — Connect your Arrivy credential

1. Go to Credentials → New Credential
2. Search for Arrivy OAuth2 API
3. Enter your Client ID and Client Secret
4. Click Connect — you'll be redirected to Arrivy to approve access
5. After approval, n8n stores your access_token

Step 6 — Use the nodes

Trigger:

1. Create a new workflow
2. Add node → search Arrivy Trigger
3. Select your credential and choose an event (e.g. Customer Created)
4. Activate the workflow — the webhook registers with Arrivy automatically

Action:

1. Add node → search Arrivy
2. Select your credential
3. Choose operation: Create Task or Get Task by ID
4. Fill in the fields and execute

---

Key API Endpoints (for reference)

Purpose	Method	URL
Get access token	POST	/api/oauth2/access_token
Validate auth	GET	/api/users/profile
Create task	POST	/api/tasks/new
Get task	GET	/api/tasks/:task_id
Subscribe webhook	POST	/api/external_integrations/n8n/hooks/subscribe
Unsubscribe webhook	DELETE	/api/external_integrations/n8n/hooks/unsubscribe/:hookId

---

Extending This Package

Adding a new trigger event

Open ArrivyTrigger.node.ts and add to the options array:

{ name: 'Task Created', value: 'task_created' },

That's it. The subscribe/unsubscribe logic is generic — it uses whatever event value the user selects.

Adding a new action (programmatic)

1. Add a new option to the operation field in Arrivy.node.ts:

{ name: 'Update Task', value: 'updateTask', action: 'Update a task' }

2. Add input fields with displayOptions: { show: { operation: ['updateTask'] } }

3. Add a branch in execute():

if (operation === 'updateTask') {
  // build payload and call this.helpers.requestWithAuthentication
}

Adding a new action (declarative)

Add a new option with a routing key — no execute() code needed:

{
  name: 'List Tasks',
  value: 'listTasks',
  action: 'List all tasks',
  routing: {
    request: {
      method: 'GET',
      url: `${ARRIVY_BASE_URL}/api/tasks`,
    },
  },
},

Adding a new node file entirely

1. Create src/nodes/Arrivy/ArrivyCustomer.node.ts
2. Register it in package.json under n8n.nodes:

"dist/nodes/Arrivy/ArrivyCustomer.node.js"

3. Rebuild: npm run build

---

Project Structure

n8n-nodes-arrivy/
├── src/
│   ├── credentials/
│   │   └── ArrivyOAuth2Api.credentials.ts   ← OAuth2 config
│   └── nodes/
│       └── Arrivy/
│           ├── Arrivy.node.ts               ← Actions (Create Task, Get Task)
│           ├── ArrivyTrigger.node.ts        ← Webhook trigger
│           └── arrivy.svg                   ← Node icon
├── dist/                                    ← Auto-generated on build (don't edit)
├── gulpfile.js                              ← Copies SVG icons to dist
├── package.json                             ← n8n node registration
├── tsconfig.json                            ← TypeScript config
└── README.md

---

Troubleshooting

Node doesn't appear in n8n:

• Make sure npm run build ran without errors
• Check package.json n8n.nodes paths match actual dist/ file paths
• Restart n8n after linking

OAuth2 fails with invalid_client:

• Double check client_id and client_secret in the credential form
• Make sure the redirect URI in your Arrivy OAuth app settings matches n8n's callback URL

Webhook not receiving events:

• Make sure the workflow is activated (toggle at top right)
• Check that n8n is publicly accessible (Arrivy needs to reach your n8n URL)
• For local development, use a tunnel like ngrok: ngrok http 5678

Create Task returns 401:

• Access token may have expired — reconnect the credential
• OAuth2 without refresh tokens means the user must re-authenticate when the token expires