Webhooks and Integrations

FractalPack integrates with host systems (ERP, WMS) to sync master data and receive real-time events. This guide covers the integrations API and webhook configuration.

Available connectors

List available connector types for your organization:

curl https://api.fractalpack.com/api/v1/integrations/connectors \
  -H "X-Api-Key: fpk_test_..."

[
  {
    "connectorType": "sap-s4hana",
    "displayName": "SAP S/4HANA",
    "description": "Sync materials and deliveries from SAP S/4HANA",
    "requiredCredentialFields": ["clientId", "clientSecret", "tokenUrl"]
  }
]

Each connector specifies which credential fields are needed during setup.

Configuring an integration

Create or update

curl -X PUT https://api.fractalpack.com/api/v1/integrations/sap-s4hana \
  -H "X-Api-Key: fpk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tenantUrl": "https://my-sap-instance.s4hana.cloud",
    "enabled": true,
    "credentials": {
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "tokenUrl": "https://my-sap-instance.authentication.us10.hana.ondemand.com/oauth/token"
    },
    "settings": {
      "webhookSecret": "whsec_abc123..."
    },
    "fieldMappings": {
      "itemMappings": {
        "sku": "MaterialNumber",
        "length": "GrossLength",
        "width": "GrossWidth",
        "height": "GrossHeight",
        "weight": "GrossWeight"
      }
    }
  }'

Credentials are stored encrypted and never returned in API responses.

List integrations

curl https://api.fractalpack.com/api/v1/integrations \
  -H "X-Api-Key: fpk_test_..."

Get a specific integration

curl https://api.fractalpack.com/api/v1/integrations/sap-s4hana \
  -H "X-Api-Key: fpk_test_..."

Delete an integration

curl -X DELETE https://api.fractalpack.com/api/v1/integrations/sap-s4hana \
  -H "X-Api-Key: fpk_test_..."

Returns 204 No Content on success.

Field mappings

Field mappings define how fields from your host system map to FractalPack entities. Each connector provides default mappings that you can customize.

Get current mappings

curl https://api.fractalpack.com/api/v1/integrations/sap-s4hana/mappings \
  -H "X-Api-Key: fpk_test_..."

Update mappings

curl -X PUT https://api.fractalpack.com/api/v1/integrations/sap-s4hana/mappings \
  -H "X-Api-Key: fpk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "itemMappings": {
      "sku": "MaterialNumber",
      "name": "MaterialDescription",
      "length": "GrossLength",
      "width": "GrossWidth",
      "height": "GrossHeight",
      "weight": "GrossWeight",
      "category": "MaterialGroup"
    },
    "deliveryMappings": {
      "orderId": "DeliveryNumber",
      "sku": "MaterialNumber",
      "quantity": "DeliveryQuantity"
    }
  }'

Get default mappings

View the connector's default mapping template:

curl https://api.fractalpack.com/api/v1/integrations/sap-s4hana/mappings/defaults \
  -H "X-Api-Key: fpk_test_..."

Reset to defaults

curl -X POST https://api.fractalpack.com/api/v1/integrations/sap-s4hana/mappings/reset \
  -H "X-Api-Key: fpk_test_..."

Connection testing

Verify that your credentials and configuration are valid:

curl -X POST https://api.fractalpack.com/api/v1/integrations/sap-s4hana/test \
  -H "X-Api-Key: fpk_test_..."

{
  "success": true,
  "message": "Connection successful"
}

Manual sync

Trigger a full sync of master data from the host system:

curl -X POST https://api.fractalpack.com/api/v1/integrations/sap-s4hana/sync \
  -H "X-Api-Key: fpk_test_..."

{
  "success": true,
  "itemsSynced": 1247,
  "errors": []
}

Sync status

Check the last sync result:

curl https://api.fractalpack.com/api/v1/integrations/sap-s4hana/sync/status \
  -H "X-Api-Key: fpk_test_..."

{
  "lastSyncAt": "2026-04-03T14:30:00Z",
  "lastSyncStatus": "success",
  "lastSyncItemCount": 1247,
  "lastError": null
}

Webhooks

Webhooks allow your host system to push real-time events to FractalPack. Each integration has a unique webhook URL.

Webhook URL format

POST https://api.fractalpack.com/api/v1/integrations/webhook/{connectorType}/{orgId}

Example:

POST https://api.fractalpack.com/api/v1/integrations/webhook/sap-s4hana/org_abc123

This endpoint is unauthenticated (no API key required) but validated via HMAC signature.

HMAC signature validation

Every webhook request must include an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body, using the webhook secret you configured during integration setup.

Header format:

X-Webhook-Signature: sha256=<hex-encoded-hmac>

Generating the signature

The signature is computed as HMAC-SHA256(webhook_secret, request_body) and hex-encoded with a sha256= prefix.

Python:

import hmac
import hashlib

def compute_signature(body: str, secret: str) -> str:
    mac = hmac.new(secret.encode(), body.encode(), hashlib.sha256)
    return f"sha256={mac.hexdigest()}"

JavaScript:

const crypto = require("crypto");

function computeSignature(body, secret) {
  const mac = crypto.createHmac("sha256", secret).update(body).digest("hex");
  return `sha256=${mac}`;
}

Webhook payload

Send a JSON payload in the request body. The format depends on the connector type and event. FractalPack dispatches the payload to the appropriate connector for processing.

curl -X POST "https://api.fractalpack.com/api/v1/integrations/webhook/sap-s4hana/org_abc123" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=5d41402abc4b2a76b9719d911017c592..." \
  -d '{"outboundDelivery": "80000001"}'

Webhook response

{
  "success": true,
  "deliveryId": "evt_abc123"
}

Webhook status

The integration's sync status tracks the latest webhook result:

{
  "lastWebhookAt": "2026-04-03T14:35:00Z",
  "lastWebhookStatus": "success",
  "lastError": null
}

Troubleshooting webhooks