> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Integrations

> Connect external tools and services to your Nudj platform

Your platform doesn't exist in isolation. You probably use Slack, email tools, CRMs, analytics platforms, and more. Custom integrations let you connect these tools so data flows smoothly between them.

<Info>
  **Settings Location**: Navigate to **Control Room > Settings > Advanced Features & Workflows > Custom Integrations** to set up connections.
</Info>

## What Can You Integrate?

Anything with an API. Common integrations:

<CardGroup cols={2}>
  <Card title="Communication" icon="message-circle">
    Slack, Microsoft Teams, email services
  </Card>

  <Card title="CRM" icon="users">
    Salesforce, HubSpot, Pipedrive
  </Card>

  <Card title="Analytics" icon="chart-bar">
    Google Analytics, Mixpanel, Amplitude
  </Card>

  <Card title="Storage" icon="database">
    AWS, Google Cloud, Dropbox
  </Card>

  <Card title="Automation" icon="zap">
    Zapier, Make, n8n
  </Card>

  <Card title="Custom APIs" icon="code">
    Your own internal systems
  </Card>
</CardGroup>

## How Integrations Work

**Webhooks** — We send data to your tool when something happens

* User completes challenge → Send data to your CRM
* Reward claimed → Log in your analytics platform
* New user joins → Add to your email list

**API Connections** — We pull/push data to keep things in sync

* Export challenge results to your spreadsheet
* Update user profiles from your CRM
* Fetch data from external systems to personalize challenges

## Setting Up an Integration

<Steps>
  <Step title="Choose Your Tool">
    Find it in our integrations marketplace or set up custom API
  </Step>

  <Step title="Get API Credentials">
    From your tool's settings (usually an API key or OAuth token)
  </Step>

  <Step title="Authenticate">
    Enter credentials or authorize connection in Nudj
  </Step>

  <Step title="Map Data">
    Tell us which Nudj events send to your tool and how
  </Step>

  <Step title="Test & Enable">
    Run a test, make sure data flows correctly, turn it on
  </Step>
</Steps>

## Webhooks: Pushing Data Out

Whenever something happens in your platform, send data somewhere:

<Accordion title="User Events" icon="users">
  * User joins community
  * User completes challenge
  * User earns reward
  * User reaches level milestone
</Accordion>

<Accordion title="Content Events" icon="file-text">
  * Challenge created/updated
  * Reward distributed
  * Post published
  * Achievement unlocked
</Accordion>

<Accordion title="Admin Events" icon="settings">
  * Settings changed
  * Team member added/removed
  * Integration toggled on/off
</Accordion>

Each event can trigger a webhook to send data to your external tool.

## API Connections: Syncing Data

Pull or push data on a schedule:

* **Sync user data** — Pull latest info from your CRM, update profiles
* **Export results** — Push challenge results to your analytics tool
* **Import content** — Pull questions from your question bank, create challenges
* **Two-way sync** — Keep data consistent between systems

## Security & Permissions

<CardGroup cols={2}>
  <Card title="API Keys" icon="key">
    Store securely, rotate regularly, use specific scopes when possible
  </Card>

  <Card title="OAuth" icon="shield">
    Safer than API keys, users authorize connections directly
  </Card>

  <Card title="IP Whitelisting" icon="lock">
    Restrict API calls to specific IP addresses
  </Card>

  <Card title="Audit Logs" icon="clipboard">
    See all integration activity for compliance
  </Card>
</CardGroup>

**Never** share API keys, commit them to GitHub, or put them in emails. Store them in a secure password manager.

## Monitoring Integrations

Track integration health:

<CardGroup cols={2}>
  <Card title="Connection Status" icon="activity">
    Is the integration currently connected?
  </Card>

  <Card title="Recent Activity" icon="history">
    When was the last successful sync or webhook?
  </Card>

  <Card title="Error Logs" icon="alert-circle">
    What went wrong and when?
  </Card>

  <Card title="Data Volume" icon="bar-chart">
    How much data are we syncing?
  </Card>
</CardGroup>

Fix errors quickly—broken integrations mean data gets out of sync.

## Common Integration Patterns

<Accordion title="Slack Notifications" icon="slack">
  When something important happens (challenge completed, new user joins), send a notification to Slack. Keep your team in the loop without them logging in.
</Accordion>

<Accordion title="CRM Sync" icon="users">
  When a user completes certain challenges, add them to a CRM segment. Track which users are most engaged in your business system.
</Accordion>

<Accordion title="Analytics Export" icon="chart-bar">
  Send all user activity to your analytics tool. Analyze engagement trends, compare with other product activity, identify patterns.
</Accordion>

<Accordion title="Email List Update" icon="mail">
  When users join or complete challenges, add them to relevant email lists. Automate follow-up campaigns.
</Accordion>

## Best Practices

**Go slow at first**

* Start with one simple integration
* Make sure it works before adding more
* Don't integrate everything at once

**Monitor actively**

* Check integration health weekly
* Set up alerts for failures
* Fix broken integrations immediately

**Keep credentials safe**

* Use API keys with minimal permissions
* Rotate keys regularly
* Never hardcode credentials
* Use environment variables

**Document your setup**

* Write down which integrations you have
* Note what data flows where
* Keep a list of who has API access

## Troubleshooting Integrations

**"Connection failed"**

* Check API credentials are correct
* Verify the external tool hasn't changed their API
* Check firewall/IP restrictions

**"Webhooks not arriving"**

* Verify webhook URL is correct
* Check your receiving system's firewall
* Test manually from our webhook tester

**"Data looks wrong"**

* Check field mappings (are we sending to the right fields?)
* Verify data format (numbers vs. strings, dates formats)
* Look at raw webhook data to see what we're actually sending

<Tip>
  **Pro tip**: Most integration problems are configuration issues, not bugs. Slow down, check settings carefully, and test each step.
</Tip>

## Next Steps

1. Identify what you want to integrate with
2. Get API credentials from that tool
3. Go to **Custom Integrations**
4. Set up your first integration (start simple)
5. Test it thoroughly before turning it on for real
6. Monitor integration health regularly

Connected systems = better data flow = smarter decisions.