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"
  }
}

Example Playbook - Syncing External Systems

Many Coperniq users have upstream/downstream systems. The often need to sync Coperniq Entities to those external systems. For example notifying sales stakeholders when a Project reaches "PTO" by updating their Salesforce instance or Slack channel.

1. The first step is to create a Coperniq Automation with a "Project Stage Updated" Trigger with the "To" Stage set to "PTO"

2. Then in the "Action" section, select "Call Webhook" and enter the URL of your external system

3. When the webhook fires, your custom middleware should catch it, process the data, and update the external system

If you need custom fields to be synced, ask your Customer Success Manager about using the Coperniq Partner API to GET /projects/:id and write to your external system.

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