feat: add n8n webhook integration guide and registration script
**Week 4 Integration Foundation:** Added comprehensive guide for n8n ↔ Jira integration: - Webhook architecture and setup - Step-by-step integration instructions - Slack integration workflow steps - Email integration for issue creation - BigBlueButton meeting link generation - Testing and troubleshooting guide Added script to register n8n webhook in Jira: - Registers webhook for PROD, MARK, SUPP, OPS projects - Captures all issue_created and issue_updated events - Includes response parsing and error handling - Success verification and troubleshooting steps **Next Steps:** 1. Run script to register webhook 2. Create n8n workflows per guide 3. Test with sample Jira issues 4. Set up Slack bot integration 5. Configure email handlers 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
SamoilenkoVadym
parent
9c535ee936
commit
f1944fb98d
2 changed files with 345 additions and 0 deletions
|
|
@ -0,0 +1,266 @@
|
|||
# n8n ↔ Jira Integration Guide
|
||||
|
||||
**Objective:** Create n8n workflows to integrate Jira with Slack, Email, and BigBlueButton
|
||||
|
||||
---
|
||||
|
||||
## Setup Overview
|
||||
|
||||
### Architecture
|
||||
```
|
||||
Jira Issue Event
|
||||
↓ (Webhook)
|
||||
n8n Webhook Receiver
|
||||
↓ (Process & Route)
|
||||
├─→ Slack Channel (Notification)
|
||||
├─→ Email Handler (Create issue)
|
||||
└─→ BigBlueButton (Generate meeting link)
|
||||
```
|
||||
|
||||
### Prerequisites
|
||||
1. n8n instance running: `https://n8n.ai-impress.com`
|
||||
2. Jira API token configured
|
||||
3. Slack workspace with bot permissions
|
||||
4. Access to n8n (via Authentik SSO)
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create n8n Webhook for Jira Events
|
||||
|
||||
### In n8n UI:
|
||||
1. Go to `https://n8n.ai-impress.com`
|
||||
2. Create new workflow: **Jira Event Handler**
|
||||
3. Add "Webhook" node:
|
||||
- Method: POST
|
||||
- Path: `/jira/events`
|
||||
- Copy the **Webhook URL**
|
||||
- Example: `https://n8n.ai-impress.com/webhook/jira/events`
|
||||
|
||||
4. Save the node
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Register Webhook in Jira
|
||||
|
||||
### Option A: Via Bash Script
|
||||
```bash
|
||||
#!/bin/bash
|
||||
JIRA_AUTH="di5zYW1vaWxlbmtvQGFpLWltcHJlc3MuY29tOkFUQVRUM3hGZkdGMEFCbEppNE1PUkoxTWx5YjZaaFItSTk4NFRZQ3JVaG9HSDN5SGYwYmpoWktrSl9wazI3czZtcmItR1ZvVnRyMGJYbVhXdFlEeVF0MUFFMMFV0NkJOcG1mcnoxQVRKbklicUFzV1Z1V2VLSHhxeUtKOGdaVkFwc2k4T0JjLWpDMkJWb0c5VFVFQkRQRE1XbUdfMEpHM3pGVTZidjhqVG1HZWN3ZTJ4bFp6VGlKbz1FMDA5MzE0MA=="
|
||||
|
||||
curl -X POST \
|
||||
"https://ai-impress.atlassian.net/rest/api/3/webhook" \
|
||||
-H "Authorization: Basic $JIRA_AUTH" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"url": "https://n8n.ai-impress.com/webhook/jira/events",
|
||||
"webhooks": [
|
||||
{
|
||||
"events": ["jira:issue_created", "jira:issue_updated"],
|
||||
"jqlFilter": "project in (PROD, MARK, SUPP, OPS)"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### Option B: Manual via Jira UI
|
||||
1. Go to https://ai-impress.atlassian.net → Settings → System → Webhooks
|
||||
2. Create Webhook:
|
||||
- URL: `https://n8n.ai-impress.com/webhook/jira/events`
|
||||
- Events: Issue created, Issue updated
|
||||
- JQL Filter: `project in (PROD, MARK, SUPP, OPS)`
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Create Slack Integration Workflow
|
||||
|
||||
### In n8n:
|
||||
1. Add nodes after Webhook:
|
||||
|
||||
**Node 2: Switch**
|
||||
- Route based on `body.webhookEvent`:
|
||||
- `jira:issue_created` → Channel 1
|
||||
- `jira:issue_updated` → Channel 2
|
||||
|
||||
**Node 3a: Set Slack Message (Created)**
|
||||
```javascript
|
||||
{
|
||||
"text": `🆕 New Issue: ${body.issue.key}`,
|
||||
"blocks": [
|
||||
{
|
||||
"type": "section",
|
||||
"text": {
|
||||
"type": "mrkdwn",
|
||||
"text": `*${body.issue.fields.summary}*\nProject: ${body.issue.fields.project.name}\nAssignee: ${body.issue.fields.assignee?.displayName || 'Unassigned'}`
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Node 3b: Set Slack Message (Updated)**
|
||||
```javascript
|
||||
{
|
||||
"text": `📝 Updated: ${body.issue.key}`,
|
||||
"blocks": [
|
||||
{
|
||||
"type": "section",
|
||||
"text": {
|
||||
"type": "mrkdwn",
|
||||
"text": `*${body.issue.fields.summary}*\nStatus: ${body.issue.fields.status.name}\nAssignee: ${body.issue.fields.assignee?.displayName || 'Unassigned'}`
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Node 4: Slack Send Message**
|
||||
- Bot Token: `xoxb-...` (from Slack workspace)
|
||||
- Channel: Select based on project
|
||||
- PROD → `#prod-jira`
|
||||
- MARK → `#mark-jira`
|
||||
- SUPP → `#supp-jira`
|
||||
- OPS → `#ops-jira`
|
||||
- Message: Use data from Set message nodes
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Create Email Integration Workflow
|
||||
|
||||
### For incoming emails → Create Jira issue:
|
||||
|
||||
**Node 1: Email Trigger** (if using IMAP)
|
||||
- Mailbox: `support@ai-impress.com`
|
||||
- Check for new emails every 1 minute
|
||||
|
||||
**Node 2: Extract Email Data**
|
||||
```javascript
|
||||
{
|
||||
"summary": `[Email] ${email.subject}`,
|
||||
"description": email.body,
|
||||
"issueType": "Task",
|
||||
"project": "SUPP"
|
||||
}
|
||||
```
|
||||
|
||||
**Node 3: Create Jira Issue**
|
||||
- Use Jira node with "Create" action
|
||||
- Map extracted data to issue fields
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Create BigBlueButton Integration
|
||||
|
||||
### For meeting link generation:
|
||||
|
||||
**Node 1: BigBlueButton Create Meeting**
|
||||
- Meeting ID: `${issue.key}-${timestamp}`
|
||||
- Meeting Name: `${issue.key}: ${issue.summary}`
|
||||
- Attendee Password: `attendee123`
|
||||
- Moderator Password: `moderator123`
|
||||
|
||||
**Node 2: Store URL in Jira**
|
||||
- Update issue custom field with meeting URL
|
||||
- Use Jira "Update" node
|
||||
|
||||
**Node 3: Notify via Slack**
|
||||
- Send message with meeting link to appropriate channel
|
||||
|
||||
---
|
||||
|
||||
## Testing the Workflow
|
||||
|
||||
### Test Jira Webhook:
|
||||
```bash
|
||||
# Create a test issue in PROD
|
||||
curl -X POST \
|
||||
"https://ai-impress.atlassian.net/rest/api/3/issues" \
|
||||
-H "Authorization: Basic $JIRA_AUTH" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"fields": {
|
||||
"project": {"key": "PROD"},
|
||||
"summary": "Test n8n integration",
|
||||
"issuetype": {"name": "Task"}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Verify in n8n:
|
||||
1. Go to workflow
|
||||
2. Click "Execute Workflow"
|
||||
3. Check execution logs
|
||||
4. Verify Slack message appears
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
Add error handlers in n8n for:
|
||||
1. Webhook validation failures
|
||||
2. Jira API rate limits
|
||||
3. Slack message delivery failures
|
||||
4. Email parsing errors
|
||||
|
||||
Use n8n "Error Handler" nodes to log and retry.
|
||||
|
||||
---
|
||||
|
||||
## Monitoring & Maintenance
|
||||
|
||||
### Check webhook status:
|
||||
```bash
|
||||
curl -X GET \
|
||||
"https://ai-impress.atlassian.net/rest/api/3/webhook" \
|
||||
-H "Authorization: Basic $JIRA_AUTH"
|
||||
```
|
||||
|
||||
### Check failed webhooks:
|
||||
```bash
|
||||
curl -X GET \
|
||||
"https://ai-impress.atlassian.net/rest/api/3/webhook/failed" \
|
||||
-H "Authorization: Basic $JIRA_AUTH"
|
||||
```
|
||||
|
||||
### Extend webhook life (30 days expiry):
|
||||
```bash
|
||||
curl -X POST \
|
||||
"https://ai-impress.atlassian.net/rest/api/3/webhook/refresh" \
|
||||
-H "Authorization: Basic $JIRA_AUTH" \
|
||||
-d '{
|
||||
"webhookIds": [10000, 10001, 10002]
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Webhook not firing | Check JQL filter in Jira webhook settings |
|
||||
| Message not in Slack | Verify bot token and channel name |
|
||||
| Rate limit errors | Add delays between n8n operations |
|
||||
| Meeting link not stored | Check custom field ID in Jira |
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ Issue created in Jira → Appears in Slack within 5 seconds
|
||||
✅ Email received → Creates SUPP ticket automatically
|
||||
✅ BBB meeting link generated and stored in issue
|
||||
✅ No API rate limit errors
|
||||
✅ All workflows handle errors gracefully
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- n8n Docs: https://docs.n8n.io
|
||||
- Jira Webhook API: https://developer.atlassian.com/cloud/jira/platform/webhooks/
|
||||
- Slack Bot API: https://api.slack.com/bot-users
|
||||
|
||||
---
|
||||
|
||||
**Next:** Execute this guide to create working integrations
|
||||
|
||||
79
opt/00-infrastructure/atlassian/scripts/11-register-n8n-webhook.sh
Executable file
79
opt/00-infrastructure/atlassian/scripts/11-register-n8n-webhook.sh
Executable file
|
|
@ -0,0 +1,79 @@
|
|||
#!/bin/bash
|
||||
|
||||
# Week 4: Register n8n Webhook in Jira
|
||||
# Creates webhook to send Jira events to n8n for processing
|
||||
|
||||
ATLASSIAN_SITE_URL="https://ai-impress.atlassian.net"
|
||||
ATLASSIAN_EMAIL="v.samoilenko@ai-impress.com"
|
||||
ATLASSIAN_API_TOKEN="ATATT3xFfGF0ABlJi4MORJ1Mlyb6ZhR-I984TYCrUhoGH3yHf0bjhZKkJ_pk27s6mrb-GVoVtr0bXmXWtYDyQt0QL0Ut6BNpmfrz1ATJnIbqAsWVuWeKHxqyKJ8gZVApsi8OBc-jC2BVoG9TUEBDPDMWmG_0JG3zFU6bv8jTmGecwe2xlZzTiJo=E0093140"
|
||||
JIRA_AUTH=$(echo -n "${ATLASSIAN_EMAIL}:${ATLASSIAN_API_TOKEN}" | base64)
|
||||
|
||||
# n8n webhook URL
|
||||
N8N_WEBHOOK_URL="https://n8n.ai-impress.com/webhook/jira/events"
|
||||
|
||||
echo "=== Week 4: Registering n8n Webhook in Jira ==="
|
||||
echo ""
|
||||
echo "Webhook URL: $N8N_WEBHOOK_URL"
|
||||
echo ""
|
||||
|
||||
# Create webhook payload
|
||||
echo "Creating webhook for Jira events..."
|
||||
|
||||
JSON_DATA='{
|
||||
"url": "'$N8N_WEBHOOK_URL'",
|
||||
"webhooks": [
|
||||
{
|
||||
"events": [
|
||||
"jira:issue_created",
|
||||
"jira:issue_updated"
|
||||
],
|
||||
"jqlFilter": "project in (PROD, MARK, SUPP, OPS)"
|
||||
}
|
||||
]
|
||||
}'
|
||||
|
||||
echo "Webhook configuration:"
|
||||
echo "$JSON_DATA" | python3 -m json.tool
|
||||
echo ""
|
||||
|
||||
# Register webhook
|
||||
echo "Registering webhook in Jira..."
|
||||
RESPONSE=$(curl -s -X POST \
|
||||
"${ATLASSIAN_SITE_URL}/rest/api/3/webhook" \
|
||||
-H "Authorization: Basic ${JIRA_AUTH}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$JSON_DATA")
|
||||
|
||||
echo "Response:"
|
||||
echo "$RESPONSE" | python3 -m json.tool
|
||||
|
||||
# Check if successful
|
||||
if echo "$RESPONSE" | grep -q '"webhookIds"'; then
|
||||
WEBHOOK_IDS=$(echo "$RESPONSE" | python3 -c "import sys, json; data=json.load(sys.stdin); print([w['id'] for w in data['webhookIds']])")
|
||||
echo ""
|
||||
echo "✓ Webhook registered successfully!"
|
||||
echo "Webhook IDs: $WEBHOOK_IDS"
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo "1. Test by creating an issue in Jira:"
|
||||
echo " - Project: PROD"
|
||||
echo " - Watch for webhook event in n8n"
|
||||
echo ""
|
||||
echo "2. Monitor webhook status:"
|
||||
echo " - Check n8n webhook logs: $N8N_WEBHOOK_URL"
|
||||
echo ""
|
||||
echo "3. View failed webhooks (if any):"
|
||||
echo " - Endpoint: /rest/api/3/webhook/failed"
|
||||
else
|
||||
ERROR=$(echo "$RESPONSE" | python3 -c "import sys, json; data=json.load(sys.stdin); print(data.get('errorMessages', [data]))" 2>/dev/null)
|
||||
echo ""
|
||||
echo "❌ Error: $ERROR"
|
||||
echo ""
|
||||
echo "Troubleshooting:"
|
||||
echo "1. Check n8n webhook URL is accessible: $N8N_WEBHOOK_URL"
|
||||
echo "2. Verify Jira authentication token is valid"
|
||||
echo "3. Check JQL filter syntax: project in (PROD, MARK, SUPP, OPS)"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== Webhook Registration Complete ==="
|
||||
Loading…
Add table
Reference in a new issue