> ## Documentation Index
> Fetch the complete documentation index at: https://help.propops.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks & Automation (n8n)

> Connect PropOps to external systems and automate workflows using webhooks and the built-in n8n integration — trigger actions on job events.

PropOps embeds [n8n](https://n8n.io) as its workflow automation engine. You can trigger workflows from external systems, list and manage workflows from the PropOps API, and subscribe to PropOps events.

<Info>
  n8n integration must be enabled and configured in **Admin → Settings → Integrations → n8n**. A self-hosted or n8n Cloud instance URL and API key are required.
</Info>

***

## n8n Workflows API

All workflow endpoints are restricted to **Staff** users with the `page.settings.configuration` permission.

### List workflows

**`GET /api/n8n/workflows?action=list`**

Returns all workflows registered in the connected n8n instance.

**Required permission:** `page.settings.configuration`\
**Account types:** Staff only

```bash theme={null}
curl -X GET "https://propops.yourcompany.com/api/n8n/workflows?action=list" \
  -H "Authorization: Bearer <token>"
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "wf_001",
      "name": "New Job Notification",
      "active": true,
      "trigger": "webhook",
      "last_executed": "2024-06-14T09:45:00Z",
      "execution_count": 142
    }
  ]
}
```

***

### Get a workflow

**`GET /api/n8n/workflows?action=get&workflow_id=<id>`**

Returns full details for a specific workflow including node configuration.

**Required permission:** `page.settings.configuration`

<ParamField query="action" type="string" required>
  Must be `get`.
</ParamField>

<ParamField query="workflow_id" type="string" required>
  n8n workflow ID.
</ParamField>

***

### Get workflow executions

**`GET /api/n8n/workflows?action=executions&workflow_id=<id>`**

Returns the execution history for a specific workflow.

**Required permission:** `page.settings.configuration`

<ParamField query="action" type="string" required>
  Must be `executions`.
</ParamField>

<ParamField query="workflow_id" type="string" required>
  n8n workflow ID.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Maximum executions to return.
</ParamField>

```bash theme={null}
curl -X GET "https://propops.yourcompany.com/api/n8n/workflows?action=executions&workflow_id=wf_001&limit=10" \
  -H "Authorization: Bearer <token>"
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "execution_id": "exec_88",
      "status": "success",
      "started_at": "2024-06-14T09:45:00Z",
      "finished_at": "2024-06-14T09:45:02Z",
      "duration_ms": 1840
    }
  ]
}
```

***

### Toggle a workflow

**`GET /api/n8n/workflows?action=toggle&workflow_id=<id>`**

Enables or disables a workflow. A disabled workflow will not execute even if triggered.

**Required permission:** `page.settings.configuration`

***

### Trigger a workflow manually

**`POST /api/n8n/workflows`**

Manually triggers a workflow with optional payload data.

**Required permission:** `page.settings.configuration`\
**Requires CSRF token.**

<ParamField body="action" type="string" required>
  Must be `trigger`.
</ParamField>

<ParamField body="workflow_id" type="string" required>
  n8n workflow ID to trigger.
</ParamField>

<ParamField body="payload" type="object">
  Optional JSON payload passed to the workflow trigger node.
</ParamField>

<ParamField body="csrf_token" type="string" required>
  CSRF token from `GET /api/security/csrf-token`.
</ParamField>

```bash theme={null}
curl -X POST "https://propops.yourcompany.com/api/n8n/workflows" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "trigger",
    "workflow_id": "wf_001",
    "payload": {
      "job_id": 1050,
      "event": "job_created"
    },
    "csrf_token": "<csrf-token>"
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "execution_id": "exec_89",
    "status": "running"
  },
  "message": "Workflow triggered"
}
```

***

### Test a workflow

**`POST /api/n8n/workflows`**

Runs a workflow in test mode — executes the logic but suppresses external side-effects (email sending, third-party API calls) if the workflow supports test mode.

**Required permission:** `page.settings.configuration`\
**Requires CSRF token.**

<ParamField body="action" type="string" required>
  Must be `test`.
</ParamField>

<ParamField body="workflow_id" type="string" required>
  n8n workflow ID.
</ParamField>

<ParamField body="csrf_token" type="string" required>
  CSRF token.
</ParamField>

***

### Get workflow stats

**`GET /api/n8n/workflows?action=stats`**

Returns aggregate execution statistics — total runs, success rate, and average duration.

**Required permission:** `page.settings.configuration`

```bash theme={null}
curl -X GET "https://propops.yourcompany.com/api/n8n/workflows?action=stats" \
  -H "Authorization: Bearer <token>"
```

```json theme={null}
{
  "success": true,
  "data": {
    "total_workflows": 8,
    "active_workflows": 6,
    "total_executions_30d": 4812,
    "success_rate_percent": 98.7,
    "avg_duration_ms": 940
  }
}
```

***

## Webhook events

When n8n is connected, PropOps publishes the following events to configured webhook workflows. You can build n8n workflows that listen for these events and forward them to Slack, email, third-party CRMs, or any HTTP endpoint.

| Event                    | Description                                       |
| ------------------------ | ------------------------------------------------- |
| `job.created`            | A new job has been raised                         |
| `job.updated`            | A job field has been changed                      |
| `job.status_changed`     | A job's status has moved to a new stage           |
| `job.completed`          | A job has been marked as completed                |
| `job.recalled`           | A completed job has been recalled                 |
| `job.assigned`           | A contractor or agent has been assigned to a job  |
| `case_note.created`      | A case note has been added to a job               |
| `document.uploaded`      | A document or photo has been uploaded to a job    |
| `invoice.created`        | An invoice has been raised for a job              |
| `invoice.paid`           | An invoice has been marked as paid                |
| `user.created`           | A new user account has been created               |
| `tenant.created`         | A new tenant record has been created              |
| `certification.expiring` | A contractor certification expires within 30 days |
| `security.alert`         | A security event has been triggered               |

### Example event payload

```json theme={null}
{
  "event": "job.status_changed",
  "timestamp": "2024-06-14T09:45:00Z",
  "instance": "https://propops.yourcompany.com",
  "data": {
    "job_uuid": "550e8400-e29b-41d4-a716-446655440001",
    "job_ref": "JOB-1050",
    "previous_status": "Open",
    "new_status": "In Progress",
    "changed_by": {
      "user_id": 12,
      "name": "Jane Smith",
      "account_type": "staff"
    }
  }
}
```

***

## Cron webhook

**`GET /api/cron/webhook`**

Internal endpoint called by the PropOps cron job to trigger scheduled workflow executions. Not intended for direct API use — the platform calls this endpoint automatically.

<Note>
  To configure scheduled automations, use n8n's built-in Schedule trigger node rather than calling the cron endpoint directly.
</Note>