Version: Arctyk ITSM v0.6.0+ Last Updated: January 2026

Integrations & Extensions¶

Welcome to the Arctyk ITSM Integrations documentation. This section provides guidance on extending Arctyk ITSM with third-party services, webhooks, workflows, and custom integrations.

Overview¶

Arctyk ITSM is designed to be extensible and can integrate with popular tools and services:

• Email - Notifications and ticket creation from email
• Slack - Real-time notifications and ticket updates
• Microsoft Teams - Chat-based notifications
• Webhooks - Custom integrations and automation
• API - Programmatic access to Arctyk ITSM data

Sections¶

Core APIs¶

• REST API - RESTful API for programmatic access to Arctyk ITSM data (Comments, Tickets, Projects, Assets)
• Workflows - Automated workflow engines, state transitions, and business logic

Notifications¶

• Email Integration - Email notifications, SMTP configuration, and email-triggered actions
• Slack Integration - Real-time Slack notifications for ticket events (planned)
• Microsoft Teams Integration - Microsoft Teams notifications and integration (planned)

Quick Start¶

REST API¶

Get a ticket using the API:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://arctyk.example.com/api/tickets/123/

Webhooks¶

Configure a webhook to POST to your server when tickets are created:

{
  "event": "ticket.created",
  "ticket_id": 123,
  "title": "New Support Request",
  "timestamp": "2026-01-03T10:00:00Z"
}

Email Notifications¶

Emails are sent on these events:

• Ticket created
• Ticket assigned to you
• Ticket status changed
• Comment added to your ticket

Integration Architecture¶

Notification Flow¶

Ticket Event
    ↓
Celery Task (async)
    ↓
Email / Slack / Teams

API Flow¶

External Service
    ↓
REST API Endpoint
    ↓
Django View / Serializer
    ↓
Database
    ↓
JSON Response

Common Use Cases¶

Use Case 1: Automated Ticket Creation¶

Create tickets programmatically from external systems:

import requests

response = requests.post(
    'https://arctyk.example.com/api/tickets/',
    headers={'Authorization': 'Bearer TOKEN'},
    json={
        'title': 'API Created Ticket',
        'description': 'Created from external system',
        'priority': 'medium'
    }
)
ticket_id = response.json()['id']

Use Case 2: Slack Notifications¶

Receive real-time Slack notifications when tickets are created or updated:

1. Configure Slack webhook in Arctyk admin
2. Select events to notify on
3. Tickets appear in your Slack channel

Use Case 3: Custom Workflow¶

Build custom business logic using the Workflow Engine:

from tickets.workflow import apply_transition

# Move ticket to next status based on conditions
apply_transition(ticket, 'in_progress')

Authentication¶

API Authentication¶

Use token-based authentication:

Authorization: Bearer YOUR_API_TOKEN

Token can be obtained from user settings or generated in admin panel.

CSRF Protection¶

Web form submissions require CSRF token:

<form method="POST">{% csrf_token %} ...</form>

Configuration¶

Environment Variables¶

# Email Configuration
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-password
EMAIL_USE_TLS=True

# Slack (planned)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# Teams (planned)
TEAMS_WEBHOOK_URL=https://outlook.webhook.office.com/webhookb2/YOUR/WEBHOOK/URL

Admin Panel Configuration¶

Some integrations can be configured in Django Admin:

1. Log in as admin
2. Navigate to Integrations section
3. Configure credentials and settings

Troubleshooting¶

Email not sending?¶

1. Check EMAIL_BACKEND configuration
2. Verify SMTP credentials
3. Check firewall/network access to email server
4. Review Django logs

API errors?¶

1. Verify authentication token
2. Check request format (JSON)
3. Review API documentation for endpoint
4. Check HTTP status codes

Webhook issues?¶

1. Verify webhook URL is correct
2. Check network connectivity
3. Review webhook delivery logs
4. Test with sample payload

Development¶

Creating a Custom Integration¶

1. Create a new Django app in src/integrations/
2. Define models for storing integration credentials
3. Create views for handling webhooks
4. Add Celery tasks for async processing
5. Register URLs in config/urls.py

Testing Integrations¶

# Test email sending
python manage.py shell
>>> from django.core.mail import send_mail
>>> send_mail('Test', 'Message', 'from@example.com', ['to@example.com'])

# Test API endpoint
curl -X GET http://localhost:8000/api/tickets/1/ \
  -H "Authorization: Bearer TOKEN"

Related Documentation¶

• API Reference
• Ticket Workflows
• Environment Variables
• Deployment Guide

Support¶

For integration questions or issues:

1. Check the relevant section above
2. Review Architecture - Workflows
3. Contact the development team
4. Check GitHub issues and discussions