Webhooks

Webhooks allow you to send automated notifications to external systems whenever specific events occur in your Coperniq Workspace. This guide explains how to set up and use webhooks effectively.

Setting Up Webhooks

1. Navigate to "Workspace Settings" > "Automations"

2. Click "Create Automation"

3. Choose your desired trigger (e.g., "Project stage updated")

4. In the Action section, select "Call webhook"

5. Enter your webhook URL where you want to receive the notifications

Available Triggers

You can configure webhooks for any automation trigger, including Record Stage Updates, Record Stage SLA Violations, Work Order Status Updates, and more.

Webhook Payload

When triggered, the webhook sends a JSON payload containing two main sections:

1. record: Contains the complete current state of the record that triggered the event

2. event: Contains details about what triggered the webhook, including:

   • The trigger type

   • Previous state (if applicable)

   • Current state

   • Timestamp of the event

Example Payload

Here's an example webhook payload from when a project moved to the Engineering stage:

{
  "record": {
    "id": 396776,
    "createdAt": "2024-12-20T14:22:31.123Z",
    "updatedAt": "2025-01-21T06:15:22.451Z",
    "title": "Elon Musk",
    "address": [
      "3500 Deer Creek Rd, Palo Alto, CA 94304"
    ],
    "geoLocation": [
      "37.394817,-122.150309"
    ],
    "jurisdiction": {
      "id": 11419,
      "name": "Palo Alto city"
    },
    "stage": {
      "id": 2014,
      "name": "Engineering"
    },
    "type": "PROJECT",
    "dealValue": 1250000,
    "ownerId": 7462,
    "city": "Palo Alto",
    "state": "CA",
    "trades": [
      "Solar",
      "Battery Storage"
    ],
    "status": "ACTIVE",
    "requestStatus": "PRIORITY",
    "primaryEmail": "[e-mail]",
    "primaryPhone": "[phone]",
    "uid": 206
  },
  "event": {
    "recordId": 396776,
    "triggerKey": "PROJECT_MOVEMENT",
    "triggerName": "Project stage updated",
    "currentStage": {
      "id": 2014,
      "name": "Engineering",
      "type": "PRODUCTION"
    },
    "previousStage": {
      "id": 2013,
      "name": "Site Survey",
      "type": "PRODUCTION"
    },
    "eventId": 432563,
    "firedAt": "2025-01-21T06:15:23.687Z"
  }
}

Best Practices

1. Use Secure URLs: If authentication is needed, include any tokens or keys as part of your webhook URL

2. Handle Duplicates: Your endpoint should be idempotent to handle potential duplicate deliveries

3. Test First: Use a service like webhook.site to inspect payload structures before connecting to production systems

4. Monitor Usage: Keep track of your webhook activity to ensure proper delivery and system health