JIRA_WEBHOOK_SETUP.md

Jira Webhook Setup Guide

This guide explains how to configure Jira webhooks for real-time updates in SprintIQ.

Prerequisites

1. Jira Admin Access: You need administrator access to your Jira instance
2. Active Jira Integration: SprintIQ must be connected to your Jira instance
3. Webhook Secret: Set up a webhook secret for security (optional but recommended)

Environment Variables

Add these to your .env.local file:

# Jira Webhook Configuration
JIRA_WEBHOOK_SECRET=your-webhook-secret-here

# If you haven't already, add your Jira credentials
JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@company.com  
JIRA_API_TOKEN=your-jira-api-token

Webhook Endpoint

Your webhook endpoint URL will be:

https://your-sprintiq-domain.com/api/webhooks/jira?organizationId=YOUR_ORG_ID

Jira Webhook Configuration

Step 1: Access Webhook Settings

1. Go to your Jira instance
2. Navigate to System → WebHooks (or Settings → System → WebHooks)
3. Click Create a WebHook

Step 2: Configure Webhook

Basic Settings:

• Name: SprintIQ Integration
• URL: https://your-sprintiq-domain.com/api/webhooks/jira?organizationId=YOUR_ORG_ID
• Description: Real-time updates for SprintIQ platform

Events to Subscribe:

✅ Issue Events:

• Issue created
• Issue updated
• Issue deleted
• Issue commented
• Issue transitioned (status changes)

✅ Sprint Events:

• Sprint started
• Sprint closed
• Sprint updated

✅ Project Events:

• Project created
• Project updated
• Project deleted

Advanced Settings:

• Exclude body: Uncheck (we need the full payload)
• SSL verification: Check if using HTTPS (recommended)

Step 3: Security Configuration (Recommended)

If you set JIRA_WEBHOOK_SECRET, configure the webhook to include a signature:

1. In webhook settings, find Advanced or Security section
2. Add your webhook secret
3. Enable signature verification

Supported Event Types

The webhook endpoint processes these Jira events:

Issue Events

• jira:issue_created - New issues
• jira:issue_updated - Issue changes (status, assignee, description, etc.)
• jira:issue_deleted - Issue deletion

Sprint Events

• sprint_started - Sprint activation
• sprint_closed - Sprint completion
• sprint_updated - Sprint modifications

Project Events

• project_created - New project creation
• project_updated - Project settings changes
• project_deleted - Project removal

Webhook Payload Processing

The webhook automatically:

1. Verifies Security: Validates webhook signature (if configured)
2. Stores Events: Logs all webhook events for audit and replay
3. Updates Database: Syncs Jira issues and sprints to SprintIQ database
4. Triggers Analysis: Queues background jobs for GraphRAG processing
5. Generates Insights: Updates AI insights when sprints complete

Data Mapping

Jira Issues → SprintIQ Tasks

• Issue Key → externalId
• Summary → title
• Description → description
• Status → Mapped to SprintIQ status (TODO, IN_PROGRESS, COMPLETED, BLOCKED)
• Priority → Mapped to SprintIQ priority (HIGH, MEDIUM, LOW)
• Assignee → assigneeId (if user exists in SprintIQ)

Jira Sprints → SprintIQ Sprints

• Sprint ID → externalId
• Sprint Name → name
• State → Mapped to SprintIQ status (PLANNED, ACTIVE, COMPLETED)
• Dates → startDate, endDate

Testing the Webhook

1. Health Check

Test if the webhook endpoint is responding:

curl -X GET "https://your-domain.com/api/webhooks/jira"

Expected response:

{
  "status": "healthy",
  "service": "jira-webhook",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0.0"
}

2. Test Event Processing

Create or update a Jira issue to trigger a webhook event.

3. Verify in SprintIQ

1. Check the Integrations page for recent activity
2. Look for new tasks appearing in your dashboard
3. Check AI insights for updated analysis

Troubleshooting

Common Issues

Webhook Not Triggering:

• Verify the URL is correct and accessible
• Check Jira webhook logs for errors
• Ensure your SprintIQ instance is publicly accessible

Authentication Errors:

• Verify webhook secret matches environment variable
• Check that organizationId parameter is correct

Data Not Syncing:

• Confirm Jira integration is active in SprintIQ
• Check server logs for processing errors
• Verify database permissions

Debug Information

Monitor webhook activity in:

1. Server Logs: Check for webhook processing messages
2. Integration Events: Database table with all webhook events
3. Background Jobs: Queue processing status

Webhook Event Schema

Example Jira issue webhook payload:

{
  "timestamp": 1640995200000,
  "webhookEvent": "jira:issue_updated",
  "user": {
    "accountId": "5b10ac8b82e05b22cc7d4ef5",
    "displayName": "John Doe",
    "emailAddress": "john@company.com"
  },
  "issue": {
    "id": "10000",
    "key": "PROJ-123",
    "fields": {
      "summary": "Implement new feature",
      "description": "Feature description here",
      "status": {
        "id": "3",
        "name": "In Progress"
      },
      "priority": {
        "id": "2", 
        "name": "High"
      },
      "assignee": {
        "accountId": "5b10ac8b82e05b22cc7d4ef5",
        "displayName": "Jane Smith"
      }
    }
  }
}

Security Best Practices

1. Use HTTPS: Always use secure webhook URLs
2. Verify Signatures: Enable webhook signature verification
3. Restrict Access: Limit webhook access to Jira IPs if possible
4. Monitor Events: Regularly review webhook event logs
5. Rotate Secrets: Periodically update webhook secrets

Rate Limiting

The webhook endpoint includes rate limiting to prevent abuse:

• 100 requests per minute per organization
• 1000 requests per hour per organization

Support

If you encounter issues:

1. Check the server logs for detailed error messages
2. Verify your Jira integration is properly configured
3. Test the webhook endpoint health check
4. Contact support with webhook event IDs for investigation

---

Next Steps:

• Configure additional Jira projects for webhook monitoring
• Set up custom alert rules for critical issue changes
• Enable advanced sprint analytics with completed sprint webhooks