Integration API

Overview

The Integration API enables you to connect Invenicum with external services and platforms. Integrations support OAuth authentication flows, webhook configurations, and connection testing.

Integration Types

Invenicum supports the following integration types:

Storage: Cloud storage providers (S3, Google Drive, Dropbox)
Version Control: Git platforms (GitHub, GitLab, Bitbucket)
Communication: Messaging platforms (Slack, Discord, Teams)
Analytics: Analytics services (Google Analytics, Mixpanel)
Custom: Custom webhook integrations

Integration Model

{
  "type": "github",
  "config": {
    "apiKey": "ghp_xxxxxxxxxxxxx",
    "organization": "my-org",
    "repository": "asset-repo",
    "webhookUrl": "https://api.invenicum.com/webhooks/github",
    "events": ["push", "pull_request", "release"]
  },
  "isActive": true,
  "lastSync": "2026-03-07T10:00:00Z"
}

Endpoints

Get Integration Statuses

GET /integrations/status

Returns the activation status of all integration types for the authenticated user. Authentication: Required Response

{
  "data": {
    "github": true,
    "slack": false,
    "s3": true,
    "google_drive": false,
    "webhook": true
  }
}

Get Integration Configuration

GET /integrations/:type

Retrieves the saved configuration for a specific integration type. Authentication: Required Path Parameters

type: The integration type (e.g., github, slack, s3)

Example Request

GET /integrations/github

Response

{
  "data": {
    "type": "github",
    "config": {
      "organization": "my-org",
      "repository": "asset-repo",
      "webhookUrl": "https://api.invenicum.com/webhooks/github",
      "events": ["push", "pull_request"]
    },
    "isActive": true,
    "createdAt": "2026-01-15T08:00:00Z",
    "lastSync": "2026-03-07T09:45:00Z"
  }
}

Sensitive fields like API keys and tokens are redacted in GET responses for security.

Test Integration

POST /integrations/test

Tests the connection to an external service before saving the configuration. Authentication: Required Request Body

{
  "type": "slack",
  "config": {
    "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX",
    "channel": "#asset-updates"
  }
}

Response (Success)

{
  "success": true,
  "message": "Successfully connected to Slack channel #asset-updates",
  "metadata": {
    "teamName": "Invenicum Team",
    "channelId": "C123456789"
  }
}

Response (Failure)

{
  "success": false,
  "message": "Invalid webhook URL or channel not found",
  "error": "SLACK_CONNECTION_FAILED"
}

Save Integration

POST /integrations

Saves or updates an integration configuration. Authentication: Required Request Body

{
  "type": "github",
  "config": {
    "apiKey": "ghp_xxxxxxxxxxxxx",
    "organization": "my-org",
    "repository": "asset-repo",
    "webhookUrl": "https://api.invenicum.com/webhooks/github",
    "events": ["push", "pull_request", "release"]
  }
}

Response

{
  "success": true,
  "message": "GitHub integration saved successfully",
  "data": {
    "type": "github",
    "isActive": true,
    "createdAt": "2026-03-07T10:30:00Z"
  }
}

Delete Integration

DELETE /integrations/:type

Removes an integration and revokes all associated credentials. Authentication: Required Path Parameters

type: The integration type to delete

Example Request

DELETE /integrations/slack

Response

{
  "success": true,
  "message": "Slack integration deleted successfully"
}

Integration Configurations

GitHub Integration

{
  "type": "github",
  "config": {
    "apiKey": "ghp_xxxxxxxxxxxxx",
    "organization": "my-org",
    "repository": "asset-repo",
    "branch": "main",
    "webhookUrl": "https://api.invenicum.com/webhooks/github",
    "webhookSecret": "your-webhook-secret",
    "events": ["push", "pull_request", "release"]
  }
}

Required Fields

apiKey: GitHub Personal Access Token with repo scope
organization: GitHub organization name
repository: Repository name

Optional Fields

branch: Target branch (default: main)
webhookUrl: Webhook endpoint URL
webhookSecret: Secret for webhook signature verification
events: Array of GitHub events to subscribe to

Slack Integration

{
  "type": "slack",
  "config": {
    "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX",
    "channel": "#asset-updates",
    "username": "Invenicum Bot",
    "iconEmoji": ":package:"
  }
}

Required Fields

webhookUrl: Slack Incoming Webhook URL
channel: Target Slack channel

AWS S3 Integration

{
  "type": "s3",
  "config": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1",
    "bucket": "my-asset-bucket",
    "pathPrefix": "assets/"
  }
}

Required Fields

accessKeyId: AWS Access Key ID
secretAccessKey: AWS Secret Access Key
region: AWS region
bucket: S3 bucket name

Optional Fields

pathPrefix: Prefix for uploaded files

Custom Webhook Integration

{
  "type": "webhook",
  "config": {
    "url": "https://myservice.com/webhooks/invenicum",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer token-here",
      "X-Custom-Header": "value"
    },
    "events": ["asset.created", "asset.updated", "asset.deleted"]
  }
}

OAuth Flows

Some integrations support OAuth 2.0 authentication for improved security.

OAuth Flow Diagram

┌──────────┐                                  ┌─────────────┐
│  Client  │                                  │   OAuth     │
│   App    │                                  │  Provider   │
└────┬─────┘                                  └──────┬──────┘
     │                                               │
     │  1. Initiate OAuth                            │
     │────────────────────────────────────────────> │
     │                                               │
     │  2. Redirect to authorization URL             │
     │ <──────────────────────────────────────────── │
     │                                               │
     │  3. User grants permission                    │
     │────────────────────────────────────────────> │
     │                                               │
     │  4. Redirect with authorization code          │
     │ <──────────────────────────────────────────── │
     │                                               │
     │  5. Exchange code for access token            │
     │────────────────────────────────────────────> │
     │                                               │
     │  6. Return access token                       │
     │ <──────────────────────────────────────────── │
     │                                               │

Initiate OAuth Flow

GET /integrations/oauth/authorize/:type

Example Request

GET /integrations/oauth/authorize/google_drive

Response

{
  "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&scope=...",
  "state": "random-state-string"
}

OAuth Callback

GET /integrations/oauth/callback/:type

Handles the OAuth provider’s redirect after user authorization. Query Parameters

code: Authorization code from the provider
state: State parameter for CSRF protection

Webhook Payloads

When events occur in Invenicum, webhooks are sent to configured endpoints.

Asset Created Event

{
  "event": "asset.created",
  "timestamp": "2026-03-07T10:30:00Z",
  "data": {
    "assetId": "asset-123",
    "name": "Product Photo.jpg",
    "category": "Images",
    "createdBy": "user-456",
    "url": "https://cdn.invenicum.com/assets/asset-123"
  }
}

Asset Updated Event

{
  "event": "asset.updated",
  "timestamp": "2026-03-07T11:00:00Z",
  "data": {
    "assetId": "asset-123",
    "changes": {
      "name": {
        "old": "Product Photo.jpg",
        "new": "Hero Image.jpg"
      },
      "tags": {
        "added": ["featured"],
        "removed": ["draft"]
      }
    },
    "updatedBy": "user-789"
  }
}

Asset Deleted Event

{
  "event": "asset.deleted",
  "timestamp": "2026-03-07T12:00:00Z",
  "data": {
    "assetId": "asset-123",
    "name": "Deprecated Asset.jpg",
    "deletedBy": "user-456"
  }
}

Webhook Signature Verification

Webhooks include a signature header for verification:

X-Invenicum-Signature: sha256=d3b07384d113edec49eaa6238ad5ff00

Verification Example (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

SDK Usage

Test an Integration

final result = await integrationService.testIntegration(
  'slack',
  {
    'webhookUrl': 'https://hooks.slack.com/services/...',
    'channel': '#asset-updates',
  },
);

if (result['success']) {
  print('Connection successful!');
} else {
  print('Error: ${result['message']}');
}

Save an Integration

await integrationService.saveIntegration(
  'github',
  {
    'apiKey': 'ghp_xxxxxxxxxxxxx',
    'organization': 'my-org',
    'repository': 'asset-repo',
  },
);

Get Integration Statuses

final statuses = await integrationService.getIntegrationStatuses();

if (statuses['github'] == true) {
  print('GitHub integration is active');
}

Delete an Integration

await integrationService.deleteIntegration('slack');

Authentication

All integration endpoints require a valid Bearer token:

Authorization: Bearer <your-token>

Error Responses

{
  "success": false,
  "message": "Invalid API credentials",
  "error": "INTEGRATION_AUTH_FAILED"
}

Common Error Codes

INTEGRATION_NOT_FOUND: The requested integration does not exist
INTEGRATION_AUTH_FAILED: Authentication with the external service failed
INVALID_CONFIG: The configuration is missing required fields
CONNECTION_TIMEOUT: The test connection timed out
WEBHOOK_DELIVERY_FAILED: Failed to deliver webhook to the configured endpoint
OAUTH_ERROR: OAuth flow failed or was cancelled

Authentication

Inventory

Management

Data & Reports

Extensions

Overview

Integration Types

Integration Model

Endpoints

Get Integration Statuses

Get Integration Configuration

Test Integration

Save Integration

Delete Integration

Integration Configurations

GitHub Integration

Slack Integration

AWS S3 Integration

Custom Webhook Integration

OAuth Flows

OAuth Flow Diagram

Initiate OAuth Flow

OAuth Callback

Webhook Payloads

Asset Created Event

Asset Updated Event

Asset Deleted Event

Webhook Signature Verification

SDK Usage

Test an Integration

Save an Integration

Get Integration Statuses

Delete an Integration

Authentication

Error Responses

Common Error Codes

Build docs developers (and LLMs) love

Authentication

Inventory

Management

Data & Reports

Extensions

​Overview

​Integration Types

​Integration Model

​Endpoints

​Get Integration Statuses

​Get Integration Configuration

​Test Integration

​Save Integration

​Delete Integration

​Integration Configurations

​GitHub Integration

​Slack Integration

​AWS S3 Integration

​Custom Webhook Integration

​OAuth Flows

​OAuth Flow Diagram

​Initiate OAuth Flow

​OAuth Callback

​Webhook Payloads

​Asset Created Event

​Asset Updated Event

​Asset Deleted Event

​Webhook Signature Verification

​SDK Usage

​Test an Integration

​Save an Integration

​Get Integration Statuses

​Delete an Integration

​Authentication

​Error Responses

​Common Error Codes

Build docs developers (and LLMs) love

Overview

Integration Types

Integration Model

Endpoints

Get Integration Statuses

Get Integration Configuration

Test Integration

Save Integration

Delete Integration

Integration Configurations

GitHub Integration

Slack Integration

AWS S3 Integration

Custom Webhook Integration

OAuth Flows

OAuth Flow Diagram

Initiate OAuth Flow

OAuth Callback

Webhook Payloads

Asset Created Event

Asset Updated Event

Asset Deleted Event

Webhook Signature Verification

SDK Usage

Test an Integration

Save an Integration

Get Integration Statuses

Delete an Integration

Authentication

Error Responses

Common Error Codes