Webhook Integration

Understanding Webhook IntegrationCopied!

Evalumo's webhook system enables real-time notifications when construction project events occur, allowing you to automate workflows across multiple platforms. The primary integration platform is Zapier, but the webhook architecture supports custom integrations for advanced automation scenarios.

Supported Trigger Events

The webhook system supports various construction project trigger events:

• new_exported_project: A project was exported

Each trigger event can be configured with custom line item expansion options to control the detail level of webhook payloads.

Webhook Lifecycle Management

Webhooks follow a subscription-based lifecycle:

1. Subscribe: Register webhook URLs when Zaps are published or reactivated

2. Receive: Process incoming event notifications with project data

3. Unsubscribe: Remove webhook registrations when Zaps are deleted or paused

Setting Up IntegrationCopied!

Subscribing to Webhook Events

To be notified when a project is exported, register the webhook using the /hook endpoint:

curl -X POST https://api.evalumo.com/hook
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "hookUrl": "https://hooks.zapier.com/hooks/catch/12345/abcdef/",
    "hookId": "hook_12345abcdef",
    "hookName": "Send project estimates to Google Sheets",
    "zapIcon": "google-sheets",
    "triggerKey": "new_exported_project",
    "lineItemsToExpand": ["TasksByItem"]
  }'

Response:

{
  "hookId": "hook_12345abcdef",
  "hookUrl": "https://hooks.zapier.com/hooks/catch/12345/abcdef/"
}

Important parameters:

• hookUrl: The Zapier webhook URL that will receive notifications

• hookId: Unique identifier for this specific webhook registration

• triggerKey: The event type that will trigger this webhook

• lineItemsToExpand: Array of line item categories to include in payloads

Webhook Payload Structure

When trigger events occur, Evalumo sends HTTP POST requests to registered webhook URLs with project data:

{
  "event": "new_exported_project",
  "timestamp": "2024-12-30T16:00:00Z",
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "projectName": "Commercial Office Building - Phase 1",
  "clientName": "Acme Construction Ltd.",
  "clientEmail": "contact@acme-construction.com",
  "totalCost": 125000.50,
  "currency": "CAD",
  "lineItems": [
    {
      "category": "materials",
      "description": "Concrete foundation materials",
      "quantity": 50,
      "unit": "cubic yards", 
      "unitCost": 110.00,
      "totalCost": 5500.00
    },
    {
      "category": "labor",
      "description": "Foundation excavation and forming",
      "quantity": 40,
      "unit": "hours",
      "unitCost": 65.00,
      "totalCost": 2600.00
    }
  ],
  "userEmail": "contractor@example.com"
}

Removing Webhook Subscriptions

To stop receiving event notifications, remove the webhook registration:

curl -X POST https://your-region-your-project.cloudfunctions.net/unsubscribeHook \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "hookUrl": "https://hooks.zapier.com/hooks/catch/12345/abcdef/",
    "hookId": "hook_12345abcdef", 
    "hookName": "Send project estimates to Google Sheets",
    "triggerKey": "estimate_completed"
  }'

The unsubscribe operation is idempotent - calling it multiple times with the same hookId will not cause errors.

Advanced Webhook PatternsCopied!

Conditional Event Processing

Filter webhook events based on project characteristics:

async function handleEstimateCompleted(projectData) {
  const { totalCost, projectName, lineItems } = projectData;
  
  // Only process large commercial projects
  if (totalCost > 50000 && projectName.includes('Commercial')) {
    await processLargeCommercialProject(projectData);
  }
  
  // Alert on high material costs
  const materialCosts = lineItems
    .filter(item => item.category === 'materials')
    .reduce((sum, item) => sum + item.totalCost, 0);
    
  if (materialCosts > totalCost * 0.6) {
    await alertHighMaterialCosts(projectData, materialCosts);
  }
}

Multi-Platform Integration

Route webhooks to multiple platforms based on event type:

const integrations = {
  'estimate_completed': [
    { platform: 'slack', webhook: process.env.SLACK_WEBHOOK },
    { platform: 'sheets', webhook: process.env.SHEETS_WEBHOOK }
  ],
  'project_created': [
    { platform: 'trello', webhook: process.env.TRELLO_WEBHOOK }
  ]
};

async function routeWebhook(eventType, projectData) {
  const targetIntegrations = integrations[eventType] || [];
  
  const promises = targetIntegrations.map(integration => 
    sendWebhook(integration.webhook, projectData, integration.platform)
  );
  
  await Promise.allSettled(promises);
}

Common Issues and Solutions

Issue: Webhook not receiving events

• Verify hookId is correctly registered

• Check that triggerKey matches expected event types

• Ensure webhook URL is accessible and returns 200 status

Issue: Incomplete webhook payloads

• Review lineItemsToExpand parameter configuration

• Confirm project has required data fields populated

• Check for API rate limiting affecting payload generation

Issue: Duplicate webhook deliveries

• Implement idempotency keys in webhook processing

• Check for multiple hook registrations with same hookId

• Verify unsubscribe calls are properly removing old registrations

Debugging Webhook Configuration

Check your current webhook registrations:

# List all exported projects to verify webhook triggers
curl -X GET "https://api.evalumo.com/exportedProject?page=0&limit=5" \
  -H "Authorization: Bearer your-access-token"

Test webhook functionality with a simple integration before building complex workflows. Start with basic project creation events and gradually add more sophisticated trigger conditions and payload processing.

By following these patterns and best practices, you can build reliable webhook integrations that keep your construction project workflows synchronized across multiple platforms and tools.