---
title: Webhook Events Reference
description: Complete reference for all webhook event types, payloads, and filtering options in TraceRTM
---

# Webhook Events Reference

This page provides a complete reference for all webhook events available in TraceRTM, including payload structures, filtering options, and example use cases.

## Event Categories

| Category | Events | Description |
|----------|--------|-------------|
| Item | `item.*` | Item lifecycle events |
| Link | `link.*` | Traceability link events |
| Project | `project.*` | Project-level events |
| Workflow | `workflow.*` | Workflow execution events |
| Import/Export | `import.*`, `export.*` | Data transfer events |
| Batch | `batch.*` | Batch operation events |
| Comment | `comment.*` | Comment and discussion events |
| User | `user.*` | User activity events |

---

## Item Events

### item.created

Triggered when a new item is created.

```json
{
  "event": "item.created",
  "timestamp": "2024-01-20T10:00:00Z",
  "data": {
    "item": {
      "id": "item_req_001",
      "type": "requirement",
      "title": "User Authentication",
      "description": "The system shall support multi-factor authentication",
      "status": "draft",
      "priority": "high",
      "assignee": {
        "id": "user_abc123",
        "email": "alice@example.com",
        "name": "Alice Smith"
      },
      "tags": ["security", "mvp"],
      "custom_fields": {
        "risk_level": "high",
        "compliance": true
      },
      "created_at": "2024-01-20T10:00:00Z",
      "created_by": {
        "id": "user_abc123",
        "email": "alice@example.com"
      }
    },
    "actor": {
      "id": "user_abc123",
      "email": "alice@example.com",
      "name": "Alice Smith",
      "type": "user"
    },
    "source": {
      "type": "api",
      "client": "web_app",
      "ip": "192.168.1.100"
    }
  }
}
```

### item.updated

Triggered when an item is updated.

```json
{
  "event": "item.updated",
  "timestamp": "2024-01-20T11:30:00Z",
  "data": {
    "item": {
      "id": "item_req_001",
      "type": "requirement",
      "title": "User Authentication (Updated)",
      "status": "draft",
      "version": 3
    },
    "changes": {
      "title": {
        "from": "User Authentication",
        "to": "User Authentication (Updated)"
      },
      "description": {
        "from": "The system shall support multi-factor authentication",
        "to": "The system shall support MFA with TOTP and SMS options"
      },
      "custom_fields.risk_level": {
        "from": "medium",
        "to": "high"
      }
    },
    "actor": {
      "id": "user_def456",
      "email": "bob@example.com",
      "name": "Bob Johnson"
    }
  }
}
```

### item.deleted

Triggered when an item is deleted.

```json
{
  "event": "item.deleted",
  "timestamp": "2024-01-20T12:00:00Z",
  "data": {
    "item": {
      "id": "item_req_002",
      "type": "requirement",
      "title": "Deleted Requirement",
      "status": "deprecated"
    },
    "deletion_type": "soft",
    "recoverable_until": "2024-02-20T12:00:00Z",
    "orphaned_links": 3,
    "actor": {
      "id": "user_abc123",
      "email": "alice@example.com"
    }
  }
}
```

### item.status_changed

Triggered when an item's status changes (workflow transition).

```json
{
  "event": "item.status_changed",
  "timestamp": "2024-01-20T14:00:00Z",
  "data": {
    "item": {
      "id": "item_req_001",
      "type": "requirement",
      "title": "User Authentication",
      "status": "approved",
      "previous_status": "in_review"
    },
    "transition": {
      "from": "in_review",
      "to": "approved",
      "workflow_id": "wf_standard",
      "transition_name": "approve"
    },
    "comment": "Approved after security review",
    "approvers": [
      {
        "id": "user_abc123",
        "email": "alice@example.com"
      }
    ],
    "actor": {
      "id": "user_abc123",
      "email": "alice@example.com"
    }
  }
}
```

### item.assigned

Triggered when an item is assigned or unassigned.

```json
{
  "event": "item.assigned",
  "timestamp": "2024-01-20T15:00:00Z",
  "data": {
    "item": {
      "id": "item_req_001",
      "type": "requirement",
      "title": "User Authentication"
    },
    "assignment": {
      "previous": null,
      "current": {
        "id": "user_def456",
        "email": "bob@example.com",
        "name": "Bob Johnson"
      }
    },
    "actor": {
      "id": "user_abc123",
      "email": "alice@example.com"
    }
  }
}
```

### item.commented

Triggered when a comment is added to an item.

```json
{
  "event": "item.commented",
  "timestamp": "2024-01-20T16:00:00Z",
  "data": {
    "item": {
      "id": "item_req_001",
      "type": "requirement",
      "title": "User Authentication"
    },
    "comment": {
      "id": "comment_abc123",
      "body": "We should also consider biometric authentication options.",
      "mentions": ["user_def456"],
      "attachments": []
    },
    "actor": {
      "id": "user_abc123",
      "email": "alice@example.com"
    }
  }
}
```

---

## Link Events

### link.created

Triggered when a traceability link is created.

```json
{
  "event": "link.created",
  "timestamp": "2024-01-20T17:00:00Z",
  "data": {
    "link": {
      "id": "link_abc123",
      "type": "verified_by",
      "source": {
        "id": "item_req_001",
        "type": "requirement",
        "title": "User Authentication"
      },
      "target": {
        "id": "item_tc_001",
        "type": "test_case",
        "title": "TC-001: Verify Login Flow"
      },
      "metadata": {
        "confidence": 0.95,
        "notes": "Primary verification test"
      }
    },
    "coverage_impact": {
      "source_coverage_before": 0.75,
      "source_coverage_after": 0.80
    },
    "actor": {
      "id": "user_abc123",
      "email": "alice@example.com"
    }
  }
}
```

### link.deleted

Triggered when a traceability link is deleted.

```json
{
  "event": "link.deleted",
  "timestamp": "2024-01-20T18:00:00Z",
  "data": {
    "link": {
      "id": "link_def456",
      "type": "traces_to",
      "source": {
        "id": "item_req_001",
        "type": "requirement"
      },
      "target": {
        "id": "item_req_002",
        "type": "requirement"
      }
    },
    "reason": "Target item deprecated",
    "coverage_impact": {
      "source_coverage_before": 0.80,
      "source_coverage_after": 0.75
    },
    "actor": {
      "id": "user_abc123",
      "email": "alice@example.com"
    }
  }
}
```

### link.suggested

Triggered when AI suggests a new link.

```json
{
  "event": "link.suggested",
  "timestamp": "2024-01-20T19:00:00Z",
  "data": {
    "suggestion": {
      "id": "sugg_abc123",
      "type": "verified_by",
      "source": {
        "id": "item_req_003",
        "type": "requirement",
        "title": "Password Requirements"
      },
      "target": {
        "id": "item_tc_005",
        "type": "test_case",
        "title": "TC-005: Password Validation"
      },
      "confidence": 0.92,
      "reasoning": "Test case validates password complexity rules mentioned in requirement",
      "matched_phrases": [
        "minimum 8 characters",
        "special character required"
      ]
    }
  }
}
```

---

## Project Events

### project.updated

Triggered when project settings are updated.

```json
{
  "event": "project.updated",
  "timestamp": "2024-01-20T10:00:00Z",
  "data": {
    "project": {
      "id": "proj_abc123",
      "name": "My Project",
      "key": "PROJ"
    },
    "changes": {
      "name": {
        "from": "Project Alpha",
        "to": "My Project"
      },
      "settings.default_workflow": {
        "from": "wf_simple",
        "to": "wf_standard"
      }
    },
    "actor": {
      "id": "user_abc123",
      "email": "alice@example.com"
    }
  }
}
```

### project.member_added

Triggered when a member is added to a project.

```json
{
  "event": "project.member_added",
  "timestamp": "2024-01-20T11:00:00Z",
  "data": {
    "project": {
      "id": "proj_abc123",
      "name": "My Project"
    },
    "member": {
      "id": "user_new123",
      "email": "newuser@example.com",
      "name": "New User",
      "role": "developer"
    },
    "actor": {
      "id": "user_abc123",
      "email": "alice@example.com"
    }
  }
}
```

---

## Workflow Events

### workflow.completed

Triggered when a workflow completes all steps.

```json
{
  "event": "workflow.completed",
  "timestamp": "2024-01-20T12:00:00Z",
  "data": {
    "workflow": {
      "id": "wf_approval_abc123",
      "name": "Requirement Approval",
      "type": "approval"
    },
    "item": {
      "id": "item_req_001",
      "type": "requirement",
      "title": "User Authentication"
    },
    "result": {
      "status": "approved",
      "final_status": "approved",
      "duration_hours": 24.5
    },
    "steps_completed": [
      {
        "name": "Technical Review",
        "completed_by": "user_tech123",
        "completed_at": "2024-01-19T14:00:00Z"
      },
      {
        "name": "Security Review",
        "completed_by": "user_sec456",
        "completed_at": "2024-01-20T10:00:00Z"
      },
      {
        "name": "Final Approval",
        "completed_by": "user_mgr789",
        "completed_at": "2024-01-20T12:00:00Z"
      }
    ]
  }
}
```

---

## Import/Export Events

### import.completed

Triggered when an import job completes.

```json
{
  "event": "import.completed",
  "timestamp": "2024-01-20T13:00:00Z",
  "data": {
    "job": {
      "id": "import_abc123",
      "source": {
        "type": "jira",
        "project": "PROJ"
      }
    },
    "results": {
      "total_processed": 500,
      "created": 450,
      "updated": 45,
      "skipped": 5,
      "failed": 0,
      "links_created": 125
    },
    "duration_seconds": 180,
    "actor": {
      "id": "user_abc123",
      "email": "alice@example.com"
    }
  }
}
```

### export.completed

Triggered when an export job completes.

```json
{
  "event": "export.completed",
  "timestamp": "2024-01-20T14:00:00Z",
  "data": {
    "job": {
      "id": "export_abc123",
      "format": "xlsx",
      "type": "full_export"
    },
    "results": {
      "items_exported": 1500,
      "links_exported": 500,
      "file_size_bytes": 2548576
    },
    "download_url": "https://api.tracertm.dev/downloads/export_abc123.xlsx",
    "expires_at": "2024-01-21T14:00:00Z"
  }
}
```

---

## Batch Events

### batch.completed

Triggered when a batch operation completes.

```json
{
  "event": "batch.completed",
  "timestamp": "2024-01-20T15:00:00Z",
  "data": {
    "job": {
      "id": "batch_abc123",
      "type": "status_update"
    },
    "results": {
      "total": 100,
      "succeeded": 98,
      "failed": 2,
      "skipped": 0
    },
    "errors": [
      {
        "item_id": "item_req_045",
        "error": "Invalid status transition"
      },
      {
        "item_id": "item_req_067",
        "error": "Item locked by another user"
      }
    ],
    "actor": {
      "id": "user_abc123",
      "email": "alice@example.com"
    }
  }
}
```

---

## Event Filtering

### Filter by Item Type

```json
{
  "events": ["item.created", "item.updated"],
  "filters": {
    "item_types": ["requirement", "test_case"]
  }
}
```

### Filter by Status

```json
{
  "events": ["item.status_changed"],
  "filters": {
    "statuses": ["approved", "rejected"]
  }
}
```

### Filter by Tags

```json
{
  "events": ["item.*"],
  "filters": {
    "tags": {
      "include": ["critical", "security"],
      "exclude": ["internal-only"]
    }
  }
}
```

### Filter by Priority

```json
{
  "events": ["item.created", "item.updated"],
  "filters": {
    "priorities": ["critical", "high"]
  }
}
```

### Filter by Custom Fields

```json
{
  "events": ["item.*"],
  "filters": {
    "custom_fields": {
      "risk_level": ["high", "critical"],
      "compliance_required": true
    }
  }
}
```

### Complex Filter Example

```json
{
  "events": ["item.status_changed", "item.updated"],
  "filters": {
    "item_types": ["requirement"],
    "statuses": ["approved"],
    "tags": {
      "include": ["mvp"]
    },
    "custom_fields": {
      "compliance_required": true
    }
  }
}
```

---

## Common Use Cases

### CI/CD Integration

Subscribe to `item.status_changed` with status filter for "approved" to trigger deployments:

```json
{
  "name": "CI/CD Trigger",
  "events": ["item.status_changed"],
  "filters": {
    "item_types": ["requirement", "user_story"],
    "statuses": ["approved"]
  }
}
```

### Slack Notifications

Subscribe to multiple events for team notifications:

```json
{
  "name": "Slack Notifications",
  "events": [
    "item.created",
    "item.status_changed",
    "item.commented"
  ],
  "filters": {
    "tags": {
      "include": ["urgent", "blocking"]
    }
  }
}
```

### Audit Logging

Subscribe to all events for comprehensive audit trail:

```json
{
  "name": "Audit Log",
  "events": ["*"],
  "filters": {}
}
```

### Coverage Monitoring

Monitor link events to track coverage changes:

```json
{
  "name": "Coverage Monitor",
  "events": ["link.created", "link.deleted"],
  "filters": {
    "link_types": ["verified_by", "satisfies"]
  }
}
```

---

## Related Documentation

- [Webhooks API](/docs/api-reference/rest-api/webhooks) - Webhook management
- [Items API](/docs/api-reference/rest-api/items) - Item operations
- [Links API](/docs/api-reference/rest-api/links) - Link operations
