slack.example.json

{
  "name": "Example Slack Credential",
  "type": "slack",
  "description": "Template for Slack webhook credential configuration in n8n",
  "instructions": [
    "1. Create Slack app at https://api.slack.com/apps",
    "2. Enable Incoming Webhooks",
    "3. Create webhook for your channel",
    "4. Copy webhook URL",
    "5. In n8n, create Slack credential and paste webhook URL"
  ],
  "credentialConfiguration": {
    "method1_webhook": {
      "name": "slack_notifications",
      "type": "Slack (Webhook)",
      "description": "Simple incoming webhook (RECOMMENDED for notifications)",
      "fields": {
        "webhookUrl": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
      },
      "setup": [
        "1. Go to https://api.slack.com/apps",
        "2. Click 'Create New App' → 'From scratch'",
        "3. Name: 'n8n Automation', Select workspace",
        "4. Click 'Incoming Webhooks' → Toggle 'Activate Incoming Webhooks' ON",
        "5. Click 'Add New Webhook to Workspace'",
        "6. Select channel (e.g., #automation-alerts)",
        "7. Copy the webhook URL",
        "8. Paste in n8n Slack credential"
      ],
      "pros": [
        "Very simple to set up",
        "No OAuth required",
        "Perfect for one-way notifications",
        "Works immediately after setup"
      ],
      "cons": [
        "Cannot read messages or interact",
        "Limited to posting messages only",
        "One webhook per channel"
      ]
    },
    "method2_oauth": {
      "name": "slack_api",
      "type": "Slack (OAuth2)",
      "description": "Full API access with OAuth (for advanced features)",
      "fields": {
        "clientId": "YOUR_CLIENT_ID",
        "clientSecret": "CONFIGURE_IN_N8N_GUI",
        "accessToken": "GENERATED_BY_OAUTH_FLOW",
        "oauthTokenData": "AUTOMATICALLY_FILLED"
      },
      "setup": [
        "1. Go to https://api.slack.com/apps",
        "2. Create app → Select workspace",
        "3. Go to 'OAuth & Permissions'",
        "4. Add scopes needed (e.g., chat:write, channels:read)",
        "5. Copy Client ID and Client Secret",
        "6. In n8n, create OAuth2 credential",
        "7. Follow OAuth flow to authorize",
        "8. n8n will store access token"
      ],
      "requiredScopes": [
        "chat:write - Send messages",
        "chat:write.public - Post to public channels without joining",
        "channels:read - List channels (if needed)",
        "users:read - Read user information (if needed)"
      ],
      "pros": [
        "Full Slack API access",
        "Can read messages, channels, users",
        "Post to any channel",
        "More flexibility"
      ],
      "cons": [
        "More complex setup",
        "Requires OAuth flow",
        "Need to manage scopes and permissions"
      ]
    }
  },
  "messageFormatting": {
    "simple": {
      "text": "Simple text message"
    },
    "withFormatting": {
      "text": "*Bold* _italic_ ~strikethrough~ `code` ```code block```"
    },
    "withMentions": {
      "text": "Hey <@USER_ID> or <!here> or <!channel>"
    },
    "withLinks": {
      "text": "Check <https://example.com|this link>"
    },
    "blockKit": {
      "blocks": [
        {
          "type": "section",
          "text": {
            "type": "mrkdwn",
            "text": "*Portainer Upgrade Success*\nServer: production-web-01"
          }
        },
        {
          "type": "divider"
        },
        {
          "type": "section",
          "fields": [
            {
              "type": "mrkdwn",
              "text": "*Environment:*\nProduction"
            },
            {
              "type": "mrkdwn",
              "text": "*Status:*\n✅ Success"
            }
          ]
        }
      ]
    }
  },
  "exampleUsage": {
    "simpleNotification": {
      "description": "Basic success/failure notification",
      "slackNode": {
        "channel": "#automation-alerts",
        "text": "✅ Portainer upgraded successfully on {{ $json.serverName }}",
        "username": "n8n Automation",
        "icon_emoji": ":robot_face:"
      }
    },
    "detailedNotification": {
      "description": "Notification with formatted details",
      "slackNode": {
        "channel": "#automation-alerts",
        "text": "*Portainer Upgrade Report*\n\n*Server:* {{ $json.serverName }}\n*Environment:* {{ $json.environment }}\n*Status:* ✅ Success\n*Timestamp:* {{ $now.toISO() }}\n*Duration:* {{ $json.duration }}s",
        "username": "Infrastructure Bot"
      }
    },
    "errorNotification": {
      "description": "Error alert with details",
      "slackNode": {
        "channel": "#alerts-critical",
        "text": "🚨 *Portainer Upgrade Failed*\n\n*Server:* {{ $json.serverName }}\n*Error:* {{ $json.error }}\n*Stage:* {{ $json.failedStage }}\n*Action Required:* Manual investigation needed\n\n<!here> Please check immediately.",
        "username": "Alert Bot",
        "icon_emoji": ":rotating_light:"
      }
    }
  },
  "bestPractices": [
    "Use dedicated channels for automation alerts (#automation-alerts)",
    "Use different channels for different severity (#alerts-info, #alerts-critical)",
    "Set meaningful username and icon for bot messages",
    "Include relevant context in messages (server name, timestamp, etc.)",
    "Use @here or @channel sparingly (only for critical alerts)",
    "Format messages with markdown for better readability",
    "Include links to relevant resources (dashboards, logs)",
    "Test messages in a private channel first",
    "Keep webhook URLs secret and rotate periodically"
  ],
  "security": {
    "warning": "Never commit webhook URLs to this repository",
    "webhookUrl": "Treat webhook URL as a password - anyone with it can post to your channel",
    "storage": "Store in n8n credentials manager, not in workflow JSON",
    "rotation": "Rotate webhooks if compromised or when team members leave",
    "permissions": "Limit webhook to specific channels, not entire workspace"
  },
  "testing": {
    "steps": [
      "1. After configuring credential, create simple test workflow",
      "2. Add Slack node with basic message",
      "3. Execute workflow manually",
      "4. Check Slack channel for message",
      "5. If not received, check webhook URL and channel"
    ],
    "testMessage": {
      "text": "🧪 Test message from n8n automation - please ignore"
    }
  },
  "troubleshooting": {
    "messageNotAppearing": [
      "Verify webhook URL is correct (starts with https://hooks.slack.com/)",
      "Check if app is installed in the workspace",
      "Verify channel exists and app has access",
      "Check n8n execution logs for errors",
      "Test webhook with curl: curl -X POST -H 'Content-type: application/json' --data '{\"text\":\"Test\"}' YOUR_WEBHOOK_URL"
    ],
    "invalidWebhook": [
      "Webhook may have been deleted - create new one",
      "Check if app was uninstalled from workspace",
      "Verify you're using correct workspace"
    ],
    "formattingIssues": [
      "Use Slack's Block Kit Builder: https://api.slack.com/block-kit/building",
      "Test markdown formatting in Slack message box first",
      "Ensure JSON is valid for block kit messages"
    ]
  },
  "migration": {
    "fromEmailToSlack": {
      "steps": [
        "1. Create Slack webhook as described above",
        "2. In workflow, replace Email Send node with Slack node",
        "3. Map data fields (subject → bold text, body → message text)",
        "4. Adjust formatting for Slack markdown",
        "5. Test with sample data",
        "6. Remove email credential if no longer needed"
      ],
      "comparison": {
        "email": {
          "subject": "Portainer Upgrade Success",
          "body": "Server: prod-01\nStatus: Success\nTime: 2025-12-21"
        },
        "slack": {
          "text": "*Portainer Upgrade Success*\n\n*Server:* prod-01\n*Status:* ✅ Success\n*Time:* 2025-12-21"
        }
      }
    }
  },
  "resources": [
    "Slack API: https://api.slack.com/",
    "Incoming Webhooks: https://api.slack.com/messaging/webhooks",
    "Block Kit Builder: https://api.slack.com/block-kit/building",
    "Message Formatting: https://api.slack.com/reference/surfaces/formatting",
    "n8n Slack Node Docs: https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.slack/"
  ]
}