zapier-make-integrations

name	zapier-make-integrations
metadata	{"category":"No-Code Low-Code and Workflow Automation"}
description	Best practices for building robust integrations, CLI apps, and complex scenarios on Zapier and Make (Integromat). Use when building custom Zapier CLI triggers/actions, Make custom apps/modules (JSON I/O, IMLS), webhooks, data transformation, rate limiting, and failure handling.
compatibility	Zapier CLI (zapier-platform-cli), Make Custom Apps API, Node.js 18+, REST/JSON APIs

Zapier & Make Integration Engineering Guidelines

This skill details design principles, implementation standards, authentication lifecycle management, and error resilience patterns for building custom Zapier CLI applications and Make (formerly Integromat) Custom Apps.

---

1. Integration Platform Architecture Comparison

Feature Dimension	Zapier Platform CLI	Make Custom Apps (Integromat)
Core Architecture	Node.js JavaScript functions executing in V8 environment	Declarative JSON configuration directives (IMLS expressions)
Trigger Mechanism	REST Hooks (Static/Subscribe) or Polling (z.request)	Instant Webhooks or Polling scenarios
Authentication	OAuth2, Session, API Key, Basic, Custom (z.dehydrate)	OAuth2, API Key, Generic HTTP connection handlers
Data Flow Logic	Code-driven JavaScript objects (bundle.inputData)	JSON Mapper directives, RPC functions, custom IMLS language
Execution Error Controls	z.errors.HaltAndCatchFire, ExpiredAuthError	Directive handlers: break, rollback, ignore, commit

---

2. Zapier Platform CLI Development

2.1 Trigger Implementation Patterns (REST Hooks vs Polling)

REST Hook Subscription (triggers/lead_created.js)

const subscribeHook = async (z, bundle) => {
  const response = await z.request({
    url: `${bundle.authData.apiUrl}/v1/webhooks/subscribe`,
    method: 'POST',
    body: {
      target_url: bundle.targetUrl,
      event: 'lead.created'
    }
  });
  return response.data; // Stores subscription metadata (e.g., webhook ID)
};

const unsubscribeHook = async (z, bundle) => {
  const hookId = bundle.subscribeData.id;
  await z.request({
    url: `${bundle.authData.apiUrl}/v1/webhooks/subscriptions/${hookId}`,
    method: 'DELETE'
  });
  return { id: hookId };
};

const parseHookPayload = (z, bundle) => {
  // Extract record array from incoming POST payload
  const rawLead = bundle.cleanedRequest;
  return [{
    id: rawLead.id,
    first_name: rawLead.first_name,
    last_name: rawLead.last_name,
    : rawLead.,
    : rawLead.
  }];
};

  =  () => {
  
   response =  z.({
    : ,
    : { : , :  }
  });
   response..;
};

. = {
  : ,
  : ,
  : {
    : ,
    : 
  },
  : {
    : ,
    : subscribeHook,
    : unsubscribeHook,
    : parseHookPayload,
    : performListFallback,
    : {
      : ,
      : ,
      : ,
      : ,
      : 
    }
  }
};

2.2 Error Management & Auth Refreshes

const performAction = async (z, bundle) => {
  const response = await z.request({
    url: `${bundle.authData.apiUrl}/v1/contacts`,
    method: 'POST',
    body: bundle.inputData
  });

  if (response.status === 401) {
    // Tells Zapier to trigger refresh token flow
    throw new z.errors.RefreshAuthError('Access token expired.');
  }

  if (response.status === 429) {
    // Rate limit hit - asks Zapier to auto-retry after delay
    const retryAfter = parseInt(response.headers.get('retry-after') || '60', 10);
    throw new z.errors.ThrottledError('Rate limit exceeded', retryAfter);
  }

  if (response.status >= 500) {
    // Transient error - trigger retry
    throw new z.errors.Error('Upstream service error', 'TransientServerError', 502);
  }

   response.;
};

---

3. Make Custom Apps Architecture (Integromat)

3.1 Module API Communication JSON Schema

Make custom app modules map API requests declaratively:

Communication Specification (api.json)

{
  "url": "/v2/customers",
  "method": "POST",
  "qs": {},
  "headers": {
    "Authorization": "Bearer {{connection.accessToken}}",
    "Content-Type": "application/json"
  },
  "body": {
    "name": "{{parameters.name}}",
    "email": "{{parameters.email}}",
    "company": "{{parameters.company}}",
    "tags": "{{split(parameters.tags, \",\")}}"
  },
  "response": {
    "output": "{{body}}",
    "error": {
      "message" 
       
    
  

3.2 Expects Interface Definition (expect.json)

[
  {
    "name": "name",
    "type": "text",
    "label": "Full Name",
    "required": true
  },
  {
    "name": "email",
    "type": "email",
    "label": "Email Address",
    "required": true
  },
  {
    "name": "company",
    "type": "text",
    "label": "Company Name",
    "required": false
  },
  {
     
     
     
     
  

---

4. Anti-Patterns & Critical Pitfalls

Anti-Pattern	Severity	Consequence	Correct Pattern
Polling without sorting by created_at desc	High	Missing data or duplicate trigger activations	Always sort trigger poll queries by descending timestamp/ID
Hardcoding access tokens without refresh handling	Critical	Workflows silently break when token expires	Implement RefreshAuthError in Zapier or OAuth refresh flow in Make
Returning single object instead of Array in Triggers	High	Zapier platform error during step execution	Triggers MUST return an array of objects [ { id: 1, ... } ]
Swallowing HTTP 429 status codes	Medium	Lost payloads under heavy API traffic	Throw ThrottledError to allow platform native retries
Missing sample payload in Zapier CLI trigger	Medium	User cannot set up downstream steps in Zapier UI	Provide accurate, comprehensive sample objects

---

5. Verification Checklist

• Zapier CLI Validation: Run zapier test with 100% test coverage for authentication, triggers, and actions.
• Deduplication Key: Verify all triggers include a unique id string field for platform deduplication engines.
• Make IMLS Syntax Check: Ensure all functions in Make JSON (e.g., {{lower(...)}}, {{split(...)}}) pass validation.
• OAuth Lifecycle: Test token expiration and refresh token retrieval workflows explicitly.