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

# Integrations

> How to configure API keys, webhooks, and external system integrations

# Integrations

Configure API keys, webhooks, and external system integrations to connect Better Data SCM with your other systems.

<Note>
  **Scope**: Tenant-scoped; requires org admin permissions\
  **Availability**: Not available in SuperAdmin
</Note>

## Understanding Integrations

### Integration Types

Integrations connect Better Data SCM with external systems:

* **API Keys**: Authenticate API requests
* **Webhooks**: Receive real-time notifications
* **External Systems**: Connect to ERP, WMS, eCommerce, etc.
* **Data Sync**: Synchronize data with external systems

**Customization Tier**: TENANT\_DEFINED (fully tenant-defined, no pack defaults)

### Integration Scope

All integrations are:

* **Tenant-Scoped**: Limited to your organization
* **Secure**: Encrypted and authenticated
* **Configurable**: You control all settings
* **Auditable**: All integration activity is logged

## API Keys

### Understanding API Keys

API keys authenticate API requests from external systems.

**Customization Tier**: TENANT\_DEFINED (you create all API keys)

### Creating API Keys

1. Navigate to **Admin** → **Integrations** → **API Keys**
2. Click **Create API Key**
3. Configure:
   * **Name**: API key name/description
   * **Permissions**: Select API permissions
   * **Expiration**: Set expiration date (optional)
   * **IP Restrictions**: Restrict to specific IPs (optional)
4. Click **Generate Key**
5. **Copy and save the key** (it won't be shown again)

<Warning>
  **Security**: API keys are shown only once. Save them securely. If lost, you must regenerate the key.
</Warning>

### Managing API Keys

1. View all API keys:
   * **Active Keys**: Currently active keys
   * **Expired Keys**: Expired keys
   * **Revoked Keys**: Revoked keys
2. Actions:
   * **Revoke**: Revoke an API key
   * **Regenerate**: Generate a new key
   * **View Details**: View key details and usage

### API Key Permissions

Configure what each API key can do:

* **Read**: Read data (GET requests)
* **Write**: Create/update data (POST, PUT, PATCH requests)
* **Delete**: Delete data (DELETE requests)
* **Admin**: Administrative operations

### API Key Best Practices

1. **Use Separate Keys**: Create separate keys for different systems
2. **Limit Permissions**: Grant minimum permissions needed
3. **Set Expiration**: Set expiration dates for keys
4. **Rotate Regularly**: Rotate keys periodically
5. **Monitor Usage**: Monitor API key usage
6. **Revoke Unused**: Revoke unused keys

## Webhooks

### Understanding Webhooks

Webhooks send real-time notifications to your systems when events occur.

**Customization Tier**: TENANT\_DEFINED (you configure all webhooks)

### Creating Webhooks

1. Navigate to **Admin** → **Integrations** → **Webhooks**
2. Click **Create Webhook**
3. Configure:
   * **Name**: Webhook name/description
   * **URL**: Webhook endpoint URL
   * **Events**: Select events to subscribe to
   * **Secret**: Webhook secret for verification
   * **Active**: Enable/disable webhook
4. Save webhook

### Webhook Events

Subscribe to events:

* **Inventory**: Inventory changes (receipts, adjustments, etc.)
* **Shipments**: Shipment events (created, shipped, received, etc.)
* **Stock Requests**: Stock request events
* **Forecasts**: Forecast events (created, updated, etc.)
* **Alerts**: Alert events (stockout, low ATP, etc.)

### Webhook Security

Configure webhook security:

* **Secret**: Webhook secret for signature verification
* **HTTPS Only**: Require HTTPS endpoints
* **IP Whitelist**: Restrict to specific IPs (optional)
* **Retry Policy**: Configure retry behavior

### Webhook Payload

Webhook payloads include:

* **Event Type**: Type of event
* **Timestamp**: Event timestamp
* **Data**: Event data
* **Signature**: Signature for verification

### Testing Webhooks

1. Click **Test Webhook** on webhook
2. Select test event
3. Send test payload
4. Verify webhook receives payload
5. Check webhook logs

## External Systems

### Understanding External Systems

Connect Better Data SCM to external systems:

* **ERP**: Enterprise Resource Planning systems
* **WMS**: Warehouse Management Systems
* **eCommerce**: eCommerce platforms
* **Marketplaces**: Marketplace platforms (Amazon, eBay, etc.)
* **Shipping Carriers**: Shipping carrier systems
* **Suppliers**: Supplier systems

**Customization Tier**: TENANT\_DEFINED (you configure all connections)

### Creating External System Connections

1. Navigate to **Admin** → **Integrations** → **External Systems**
2. Click **Create Connection**
3. Configure:
   * **Name**: Connection name
   * **Type**: System type (ERP, WMS, eCommerce, etc.)
   * **Endpoint**: System endpoint URL
   * **Authentication**: Authentication method (API Key, OAuth, etc.)
   * **Credentials**: System credentials
   * **Sync Settings**: Data sync settings
4. Save connection

### External System Types

**ERP**: Enterprise Resource Planning

* SAP, Oracle, NetSuite, etc.
* Sync: Products, inventory, orders

**WMS**: Warehouse Management System

* Manhattan, HighJump, etc.
* Sync: Inventory, shipments, locations

**eCommerce**: eCommerce Platform

* Shopify, WooCommerce, Magento, etc.
* Sync: Products, inventory, orders

**Marketplace**: Marketplace Platform

* Amazon, eBay, Walmart, etc.
* Sync: Products, inventory, orders

**Shipping Carrier**: Shipping Carrier

* FedEx, UPS, DHL, etc.
* Sync: Shipments, tracking

**Supplier**: Supplier System

* Supplier portals, EDI, etc.
* Sync: Purchase orders, shipments

### Data Sync Configuration

Configure data synchronization:

* **Sync Direction**: One-way or two-way
* **Sync Frequency**: Real-time, scheduled, manual
* **Sync Scope**: What data to sync
* **Mapping**: Field mappings
* **Transformations**: Data transformations

## Integration Mappings

### Understanding Integration Mappings

Map data between Better Data SCM and external systems.

**Customization Tier**: TENANT\_DEFINED (you define all mappings)

### Creating Mappings

1. Navigate to **Admin** → **Integrations** → **Mappings**
2. Click **Create Mapping**
3. Configure:
   * **Source System**: Better Data SCM
   * **Target System**: External system
   * **Entity Type**: Product, Inventory, Order, etc.
   * **Field Mappings**: Map fields between systems
   * **Transformations**: Data transformations
4. Save mapping

### Mapping Types

**Product Mapping**: Map products

* Product codes
* Product attributes
* Product categories

**Inventory Mapping**: Map inventory

* Inventory levels
* Location mappings
* Channel mappings

**Order Mapping**: Map orders

* Order numbers
* Order status
* Order items

## Integration Monitoring

### Viewing Integration Activity

1. Navigate to **Admin** → **Integrations** → **Activity**
2. View integration activity:
   * **API Calls**: API request/response logs
   * **Webhook Deliveries**: Webhook delivery status
   * **Sync Jobs**: Data sync job status
   * **Errors**: Integration errors

### Integration Health

Monitor integration health:

* **Status**: Active, Inactive, Error
* **Last Sync**: Last successful sync
* **Error Rate**: Error rate percentage
* **Latency**: Response time

### Troubleshooting Integrations

1. Review integration logs
2. Check error messages
3. Verify credentials
4. Test connection
5. Review sync status

## What Success Looks Like

### Integration Success

* ✅ API keys properly configured
* ✅ Webhooks delivering notifications
* ✅ External systems connected
* ✅ Data syncing correctly
* ✅ Integration errors resolved

### Security Success

* ✅ API keys secured
* ✅ Webhooks authenticated
* ✅ External connections encrypted
* ✅ Access controlled
* ✅ Activity monitored

## Common Pitfalls

### 1. Not Securing API Keys

**Problem**: API keys exposed or shared insecurely.

**Solution**: Secure API keys:

* Store keys securely
* Don't share keys
* Rotate keys regularly
* Use separate keys per system

**How to avoid**: Make key security part of integration setup.

### 2. Not Testing Webhooks

**Problem**: Webhooks configured but not tested.

**Solution**: Test webhooks:

* Send test payloads
* Verify webhook receives payloads
* Check webhook logs
* Monitor webhook delivery

**How to avoid**: Make testing part of webhook setup.

### 3. Not Monitoring Integrations

**Problem**: Integrations configured but not monitored.

**Solution**: Monitor integrations:

* Review integration activity
* Check error rates
* Monitor sync status
* Review logs regularly

**How to avoid**: Make monitoring part of integration management.

### 4. Not Mapping Data Correctly

**Problem**: Data mappings incorrect, causing sync errors.

**Solution**: Map data correctly:

* Review field mappings
* Test mappings
* Verify transformations
* Document mappings

**How to avoid**: Make mapping review part of integration setup.

## Troubleshooting

### API Key Not Working

**Symptoms**: API requests failing with authentication errors.

**Possible causes:**

1. API key incorrect
2. API key expired
3. API key revoked
4. Permissions insufficient
5. IP restrictions

**Steps to resolve:**

1. Verify API key is correct
2. Check API key expiration
3. Verify API key is active
4. Check API key permissions
5. Review IP restrictions

### Webhook Not Delivering

**Symptoms**: Webhooks configured but not receiving events.

**Possible causes:**

1. Webhook not active
2. Webhook URL incorrect
3. Webhook endpoint down
4. Events not subscribed
5. Security verification failing

**Steps to resolve:**

1. Verify webhook is active
2. Check webhook URL
3. Test webhook endpoint
4. Verify event subscriptions
5. Check security settings

### External System Not Syncing

**Symptoms**: External system connected but not syncing data.

**Possible causes:**

1. Connection not active
2. Credentials incorrect
3. Sync not configured
4. Mapping incorrect
5. System error

**Steps to resolve:**

1. Verify connection is active
2. Check credentials
3. Review sync configuration
4. Verify mappings
5. Check system logs

***

## Related Pages

* [Admin Overview](/admin/overview)
* [API Reference](/api-reference)
* [Configuration Map](/admin/configuration-map)

***

## Permissions & Roles

<Warning>
  Configuring integrations requires tenant admin permissions. Integration configurations affect data synchronization and system connectivity. All integration configurations are tenant-scoped and not available in SuperAdmin.
</Warning>