Custom Apps

Custom apps are private integrations that you create directly from your SeloraX dashboard. Unlike platform apps that go through the marketplace and OAuth install flow, custom apps are auto-installed to your store and give you API credentials immediately.

Use custom apps when you need to:

• Build a private integration for your own store
• Connect third-party tools (ERP, accounting, shipping) to your store data
• Automate workflows with scripts or cron jobs
• Test API functionality before building a full platform app

Custom Apps vs Platform Apps

Creating a Custom App

Step 1: Open the Wizard

Navigate to Settings > Apps > Manage in your dashboard. At the top of the page, click Create Custom App.

Step 2: App Details

Enter a name for your app and an optional description. The name helps you identify the app later if you create multiple integrations.

Step 3: API Scopes

Select the permissions your app needs. Only request what you actually use -- you can update scopes later.

Step 4: Webhooks (Optional)

If you want to receive real-time event notifications, enter your webhook URL and select the event topics you want to subscribe to.

Webhook URL -- The HTTPS endpoint where SeloraX will send event payloads. Example: https://my-server.example.com/webhooks/selorax

Event Topics:

• Order Events -- order.created, order.updated, order.status_changed
• Product Events -- product.created, product.updated, product.deleted
• Customer Events -- customer.created, customer.updated
• Inventory -- inventory.updated

You can skip this step and add webhooks later from the Webhooks tab.

Step 5: Review and Create

Review your configuration and click Create App. The platform creates the app, installs it to your store, and generates your API credentials.

Step 6: Save Your Credentials

After creation, you see your credentials one time only:

• Access Token -- Used to authenticate API requests via Bearer auth. Format: sx_at_<96 hex chars>
• Client ID -- Your app's public identifier. Format: sx_app_<32 hex chars>
• Client Secret -- Used for client credentials server-to-server auth. Format: sx_secret_<64 hex chars>
• Webhook Signing Secret -- Used to verify webhook payloads (only shown if you configured webhooks). Format: whsec_<64 hex chars>

Copy and store these immediately. Once you close the dialog, you cannot retrieve the access token, client secret, or signing secret again. If you lose them, you can regenerate a new token from the Manage page, but the old token is permanently revoked.

Making API Calls

Use the access token in the Authorization header:

curl -X GET "https://api.selorax.io/api/apps/v1/orders?page=1&limit=10" \
  -H "Authorization: Bearer sx_at_your_access_token_here"

Or use client credentials for server-to-server requests:

curl -X GET "https://api.selorax.io/api/apps/v1/orders?page=1&limit=10" \
  -H "X-Client-Id: sx_app_your_client_id" \
  -H "X-Client-Secret: sx_secret_your_client_secret" \
  -H "X-Store-Id: 22"

Node.js Example

const axios = require("axios");
 
const API_URL = "https://api.selorax.io/api";
const ACCESS_TOKEN = "sx_at_your_access_token_here";
 
async function getOrders() {
  const response = await axios.get(`${API_URL}/apps/v1/orders`, {
    headers: {
      Authorization: `Bearer ${ACCESS_TOKEN}`,
    },
    params: { page: 1, limit: 50 },
  });
 
  console.log("Orders:", response.data.data);
  return response.data;
}
 
getOrders();

Python Example

import requests
 
API_URL = "https://api.selorax.io/api"
ACCESS_TOKEN = "sx_at_your_access_token_here"
 
response = requests.get(
    f"{API_URL}/apps/v1/orders",
    headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
    params={"page": 1, "limit": 50},
)
 
data = response.json()
print(f"Found {len(data.get('data', []))} orders")

Response Format

All API responses follow a standard envelope:

{
  "data": [...],
  "pagination": { "page": 1, "limit": 50, "total": 100 },
  "status": 200
}

Error responses include a code field:

{
  "message": "Insufficient scope. Required: read:orders",
  "code": "insufficient_scope",
  "status": 403
}

Try It

Use your custom app access token to test the Orders API:

Receiving Webhooks

If you configured webhooks during creation, SeloraX sends HMAC-signed HTTP POST requests to your webhook URL when events occur.

Verifying Webhook Signatures

Every webhook delivery includes a signature header. Verify it using your signing secret:

const crypto = require("crypto");
 
function verifyWebhook(rawBody, signature, timestamp, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}
 
// In your webhook handler:
app.post("/webhooks/selorax", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-selorax-signature"];
  const timestamp = req.headers["x-selorax-timestamp"];
  const secret = "whsec_your_signing_secret_here";
 
  const rawBody = req.body.toString("utf8");
 
  if (!verifyWebhook(rawBody, signature, timestamp, secret)) {
    return res.status(401).send("Invalid signature");
  }
 
  const { event_topic, data } = JSON.parse(rawBody);
  console.log(`Received ${event_topic}:`, data);
 
  // Process the event...
  res.status(200).send("OK");
});

Webhook Payload Structure

{
  "event_id": "evt_abc123",
  "event_topic": "order.status_changed",
  "store_id": 22,
  "store_name": "My Store",
  "timestamp": "2026-03-01T10:30:00.000Z",
  "data": {
    "order_id": 1001,
    "status": "confirmed",
    "customer_name": "John Doe",
    "customer_phone": "+8801712345678"
  }
}

The fields included in data depend on the webhook's permissions. When creating webhooks from the Webhooks tab, you can select which resource data to include (orders, products, customers, inventory).

Managing Custom Apps

Regenerate Access Token

If your token is compromised or lost, go to Settings > Apps > Manage, find your custom app in the table, and click the rotate icon. This generates a new token and immediately revokes the old one.

Delete a Custom App

Deleting a custom app:

• Revokes all API tokens
• Disables all webhook subscriptions
• Marks the installation as uninstalled

Any integration using the app's credentials will stop working immediately.

Adding Webhooks Later

If you skipped webhooks during app creation, or want to add more subscriptions:

1. Go to Settings > Apps > Webhooks
2. Click Create Webhook
3. Enter a name, target URL, select event topics, and choose payload permissions
4. Save -- you receive a signing secret (shown once)

You can create multiple webhook subscriptions pointing to different URLs or listening to different events.

Token Expiry

Custom app access tokens are valid for 1 year. When a token expires, regenerate it from the Manage page. The API returns a 401 response when the token has expired:

{
  "message": "Token expired or invalid",
  "code": "token_expired",
  "status": 401
}

Next Steps

• API Reference -- Full documentation for all available endpoints.
• Webhooks -- Learn about event topics, retry policies, and delivery logs.
• Orders API -- Query, filter, and manage orders.
• Products API -- Access product catalog data.