Humi → Productive.io Time Off Integration

This serverless integration automatically syncs approved time off requests from Humi to Productive.io using Zapier webhooks.

🏗️ Architecture

• Frontend: Vercel Serverless Functions (Node.js)
• Database: Supabase (PostgreSQL)
• Integration: Zapier webhooks → API → Productive.io API
• Hosting: Vercel (free tier)

🚀 Quick Setup

1. Supabase Setup

You mentioned you already have your Supabase database ready with the users table. That's all you need!

2. Productive.io API Setup

1. Go to Productive.io → Settings → API integrations
2. Generate a new API token
3. Note your Organization ID

3. Vercel Deployment

1. Clone/Fork this repository

2. Connect to Vercel:

   • Go to vercel.com
   • Import your GitHub repository
   • Vercel will automatically detect this as a serverless functions project

3. Add Environment Variables in Vercel:

   SUPABASE_URL=your_supabase_project_url
   SUPABASE_ANON_KEY=your_supabase_anon_key
   SUPABASE_SECRET=your_supabase_secret
   PRODUCTIVE_API_TOKEN=your_productive_api_token
   PRODUCTIVE_ORG_ID=your_productive_organization_id
   

4. Deploy: Vercel will automatically build and deploy

4. Test the Integration

After deployment, test your webhook endpoint:

• Webhook: POST https://your-app.vercel.app/api/webhook/humi-timeoff (This is what Zapier calls)

📋 API Endpoints

Webhook Endpoint

POST /api/webhook/humi-timeoff

Receives Zapier webhooks when time off is approved in Humi.

Expected payload:

{
  "humi_uid": "12345",
  "start_date": "2024-01-15",
  "end_date": "2024-01-16",
  "status": "approved",
  "time_off_type": "vacation",
  "days_count": 2
}

🔧 Configuration

Environment Variables

Variable	Description	Required
SUPABASE_URL	Your Supabase project URL	✅
SUPABASE_ANON_KEY	Supabase anonymous/public key	✅
SUPABASE_SECRET	Supabase secret (if needed for auth)	⚠️
PRODUCTIVE_API_TOKEN	Your Productive.io API token	✅
PRODUCTIVE_ORG_ID	Your Productive.io organization ID	✅

Supabase Configuration

Make sure your users table matches this schema:

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  humi_uid VARCHAR(255) UNIQUE NOT NULL,
  email VARCHAR(255) NOT NULL,
  name VARCHAR(255),
  productive_uid VARCHAR(255), -- Cached for performance
  created_at TIMESTAMP DEFAULT NOW()
);

🔗 Zapier Setup

1. Create a new Zap in Zapier
2. Trigger: Humi → "Time Off Request Approved" (or similar)
3. Action: Webhooks by Zapier
   • Method: POST
   • URL: https://your-app.vercel.app/api/webhook/humi-timeoff
   • Headers: Content-Type: application/json
   • Data: Map the Humi fields to the expected JSON structure

🧪 Testing

Local Development

# Install dependencies
npm install

# Run locally (requires Vercel CLI)
npx vercel dev

Manual Webhook Testing

# Test the webhook endpoint
curl -X POST https://your-app.vercel.app/api/webhook/humi-timeoff \
  -H "Content-Type: application/json" \
  -d '{
    "humi_uid": "12345",
    "start_date": "2024-01-15",
    "end_date": "2024-01-16",
    "status": "approved",
    "time_off_type": "vacation"
  }'

📊 Monitoring

• Function Logs: Available in Vercel dashboard

🚨 Troubleshooting

Common Issues

1. "User not found"

   • Ensure the user was added to Humi (triggers Zapier to add to Supabase)
   • Check if user exists in Supabase users table via Supabase dashboard
   • If missing, manually add via Supabase dashboard or trigger Humi user creation workflow

2. "User not found in Productive.io"

   • Verify the email address exists in Productive.io
   • Check the email spelling in your user mapping

3. "Productive.io API error"

   • Verify your API token and organization ID
   • Check if the user has proper permissions in Productive.io

4. Function timeout

   • Check the Vercel function logs
   • Ensure Supabase and Productive.io are responding

Debugging

Check logs in Vercel Functions dashboard for any errors.

🔄 How It Works

User Management Flow:

1. User added to Humi → Triggers Zapier workflow
2. Zapier adds user to Supabase → Populates users table with Humi UID, name, email

Time Off Sync Flow:

1. Time off approved in Humi → Triggers Zapier
2. Zapier sends webhook → POST /api/webhook/humi-timeoff
3. Function looks up user → Queries Supabase users table for email
4. Function finds Productive.io user → Uses email to find person ID
5. Function creates booking → Calls Productive.io API

🎯 Future Enhancements

This integration is designed to grow with your needs:

• Real-time Dashboard: Show live integration status
• Mobile App: React Native app for mobile management
• Multi-tenant: Support multiple companies
• Advanced Workflows: Approval processes, notifications
• Additional Integrations: Slack, Teams, other HR tools

📞 Support

• Check Vercel function logs for any errors
• Ensure all environment variables are properly set