What is a violation?
A violation is a record of a detected rule breach. When a detection action finds objects that match the configured criteria, and the workflow’s consolidation logic evaluates totrue, a violation is created.
Violation data includes:
| Field | Description |
|---|---|
branch_rule_id | The rule that triggered the violation |
started_at / ended_at | When the violation occurred |
main_attachment | Video clip or full image URLs |
sub_attachment | Detection crop or thumbnail URLs |
timestamp | Creation time |
note | Additional context from the detection |
status | Current status for escalation tracking |
Creating violations
The create_violation action
Thecreate_violation business action collects attachments from previous detection actions and creates violation records. It iterates through all non-business actions in the workflow, extracts their attachments, uploads them to Supabase storage, and creates violation records via the insert-violation edge function.
For detailed information about the create_violation action, see the create violation documentation.
Attachment modes
- Single attachments
- Combined attachments
By default, each detection creates a separate violation. This creates a one-to-one mapping between detections and violations.Example flow:
- Detection 1 produces attachment 1 → Violation 1 created
- Detection 2 produces attachment 2 → Violation 2 created
- Detection 3 produces attachment 3 → Violation 3 created
Attachment types
The violation system supports multiple attachment formats:| Type | Description | Example |
|---|---|---|
file | Local file path | /data/detect/abc123_detection.jpg |
url | Already-uploaded URL | https://storage.supabase.co/... |
base64 | Base64-encoded image | Inline image data |
Escalation process
Violations can be escalated to brands through multiple channels based on configuration. The escalation flow checks each configured integration and sends notifications accordingly.Escalation flow
- Violation created - The create_violation action completes successfully
- Check brand configuration - The system checks which integrations are enabled for the brand
- Send notifications - Each enabled integration receives the violation data
Integration priority
When multiple integrations are configured, they execute in this order:| Priority | Integration | Purpose |
|---|---|---|
| 1 | Webhook | Immediate programmatic notification to external systems |
| 2 | Human-readable notification to configured recipients | |
| 3 | Zoho | Ticket creation in Zoho Desk for tracking |
Integration methods
Webhook integration
Send violation data to an external system via HTTP POST.- Configuration
- Payload contents
- Error handling
Configure the webhook URL on the brand settings:
| Field | Description |
|---|---|
webhook_url | The endpoint URL to receive violation data |
webhook_secret | Optional secret for request signing |
Email integration
Send violation alerts via email to configured recipients. Email contents:- Video or image attachment (embedded or linked)
- Detection detail thumbnail
- Violation timestamp
- Rule description
- Branch and brand information
| Field | Description |
|---|---|
business_action_email | Recipient email address on the brand |
| SMTP credentials | Server configuration for sending |
Zoho integration
Create support tickets in Zoho Desk for violations, enabling brands to track and manage violations through their existing ticketing workflow.- Setup requirements
- Ticket creation
- Rate limiting
Configure Zoho OAuth credentials on the brand:
| Field | Description |
|---|---|
zoho.enabled | Must be true to enable integration |
zoho.org_id | Zoho organization ID |
zoho.department_id | Target department for tickets |
zoho.contact_id | Contact to associate with tickets |
zoho.client_id | OAuth client ID |
zoho.client_secret | OAuth client secret |
zoho.refresh_token | OAuth refresh token |
zoho.api_region | API region (e.g., “sa” for Saudi Arabia) |
Configuring integrations
Per-brand configuration
Each brand can have different integration settings. Configure these in the brand settings:| Integration | Required fields |
|---|---|
business_action_email | |
| Zoho | zoho.enabled, zoho.org_id, zoho.department_id, zoho.contact_id, OAuth credentials |
| Webhook | webhook_url, optionally webhook_secret |
Testing integrations
Before deploying to production:- Email - Send a test violation to verify delivery and formatting
- Zoho - Create a test ticket to verify OAuth and department configuration
- Webhook - Use a tool like webhook.site to inspect payload format
Error handling and troubleshooting
Violation not created
Violation not created
Check:
- Did the detection action return
is_success = true? - Did consolidation logic evaluate to
true? - Were attachments successfully uploaded to Supabase?
insert-violation calls in the logs to see the response.Email not sent
Email not sent
Verify:
business_action_emailis set on the brand- Attachment URLs are valid (not local paths)
- SMTP credentials are correct
Zoho ticket not created
Zoho ticket not created
Check:
zoho.enabledistrueon the brand- OAuth tokens are valid (not expired)
- Department ID and contact ID exist in Zoho
Monitoring violations
Key metrics to track
| Metric | Description |
|---|---|
| Violations per hour | Rate of violation creation |
| Attachment upload success rate | Percentage of successful uploads |
| Integration delivery rate | Success rate for each notification method |
| Average processing time | Time from detection to violation creation |
Execution logs
Each violation creation is logged with details including:- Number of violations created
- Attachment URLs
- Integration delivery status
- Any errors encountered