API Integration Guide

Learn how to connect your Appivo application with external services using the integration framework.

Integration Types

Appivo supports multiple integration methods:

Webhooks

Send data to external systems when events occur.

Creating a Webhook

1. Navigate to Integrations
2. Click Add Webhook
3. Configure the webhook:

Example: Order Notification

Webhook: Notify Fulfillment
Trigger: Order created
URL: https://fulfillment.example.com/orders
Method: POST
Headers:
  Authorization: Bearer {{config.api_key}}
  Content-Type: application/json
Payload:
  {
    "order_id": "{{order.id}}",
    "customer": "{{order.customer_name}}",
    "items": {{order.items}},
    "total": {{order.total}}
  }

Webhook Security

Secure your webhooks:

• Use HTTPS endpoints only
• Include authentication headers
• Validate webhook signatures
• Implement retry logic

Calling External APIs

Use the WEBHOOK action to call external services.

Basic API Call

// In a SCRIPT action
const response = await context.http({
    url: 'https://api.example.com/data',
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + context.getConfig('api_key')
    }
});

if (response.status === 200) {
    const data = response.data;
    // Process data
}

POST Request

const response = await context.http({
    url: 'https://api.example.com/orders',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + context.getConfig('api_key')
    },
    data: {
        customer_id: params.customerId,
        items: params.items
    }
});

Authentication Methods

API Keys

Simple token-based authentication:

Headers:
  Authorization: Bearer YOUR_API_KEY
  X-API-Key: YOUR_API_KEY

OAuth 2.0

For services requiring OAuth:

1. Configure OAuth credentials
2. Implement token refresh
3. Store tokens securely

Basic Authentication

Username/password authentication:

Headers:
  Authorization: Basic base64(username:password)

REST Rules

Create API endpoints that external systems can call.

Creating a REST Rule

1. Navigate to Rules
2. Click Add Rule
3. Select REST type
4. Configure:

Example: External Order Endpoint

Rule: Receive External Order
Type: REST
Endpoint: /api/orders/create
Method: POST
Authentication: API Key

Action: SCRIPT
  1. Validate incoming data
  2. Create order record
  3. Trigger fulfillment
  4. Return confirmation

Request Handling

exports.execute = async function(context, params) {
    // Access request data
    const orderData = params.body;

    // Validate
    if (!orderData.customer_id) {
        return {
            status: 400,
            error: 'customer_id is required'
        };
    }

    // Process
    const order = await context.createRecord('Order', {
        customer_id: orderData.customer_id,
        items: orderData.items,
        status: 'New'
    });

    return {
        status: 201,
        data: { order_id: order.id }
    };
};

SCIM 2.0 Integration

Synchronize users and groups with identity providers.

Supported Operations

• User provisioning
• User updates
• User deprovisioning
• Group management
• Attribute mapping

Configuration

1. Enable SCIM in Integrations
2. Generate SCIM endpoint URL
3. Create authentication token
4. Configure in identity provider

Error Handling

Retry Configuration

Configure retry behavior for failed calls:

Error Responses

Handle errors gracefully:

try {
    const response = await context.http({
        url: 'https://api.example.com/data',
        method: 'GET'
    });

    if (response.status !== 200) {
        context.log.error('API error', {
            status: response.status,
            body: response.data
        });
        return { success: false, error: 'API call failed' };
    }

    return { success: true, data: response.data };

} catch (error) {
    context.log.error('Request failed', error);
    return { success: false, error: error.message };
}

Best Practices

Security

• Store credentials in configuration
• Use HTTPS for all calls
• Validate incoming data
• Log sensitive operations

Reliability

• Implement retry logic
• Handle timeouts
• Queue requests when needed
• Monitor for failures

Performance

• Cache responses when appropriate
• Use async processing
• Batch operations
• Set appropriate timeouts

Monitoring

• Log all API calls
• Track success/failure rates
• Alert on errors
• Review usage patterns

Common Patterns

Data Synchronization

Pattern: Sync External Data
Schedule: Every hour

Steps:
  1. Fetch data from external API
  2. Compare with local records
  3. Create/update/delete as needed
  4. Log sync results

Event Broadcasting

Pattern: Broadcast Events
Trigger: Record created/updated

Steps:
  1. Event occurs in Appivo
  2. Webhook sends to external systems
  3. Wait for acknowledgment
  4. Log delivery status

Two-Way Integration

Pattern: Bidirectional Sync
Components:
  - Outbound: Webhooks for changes
  - Inbound: REST endpoints for external changes
  - Conflict: Resolution rules

Next Steps

• Rules and Actions - Create integration triggers
• Security - Secure your integrations
• Data Modeling - Design for integration