Mobitsa Developers

API and webhook documentation for connecting an external system to a Mobitsa online store.

This page describes the shared contract. Keys, permissions, and the webhook URL are configured only inside the selected workspace.

Overview

Use the API to read and update data. Webhooks notify the external system about events without constant polling.

Base URLhttp://mobitsa.pw/api/store/v1

Server-side authenticationAuthorization: Bearer mbs_live_…

Up to 120 requests per minute per key

API methods

Every request is scoped to the selected site and key permissions. Secret values are never shown on the public page.

Orders

GET/orders List orders

GET/orders/{id} Get one order

PATCH/orders/{id}/status Update order status

Products and variants

GET/products Get a page of products

GET/products/{id} Get a product and its variants

PATCH/products/{id}/stock Update stock for a simple product

GET/products/{id}/variants Get product variants

GET/products/{id}/variants/{variantId} Get one variant

PATCH/products/{id}/variants/{variantId}/stock Update variant stock

Status update example

Supported statuses: PROCESSING, SHIPPED, COMPLETED, CANCELLED, REFUNDED, FAILED

PATCH /api/store/v1/orders/42/status
Content-Type: application/json

{
  "status": "PROCESSING"
}

Events and delivery

Mobitsa sends a POST request to the saved HTTPS address. One event envelope makes handling and extending an integration predictable.

Available events

order.createdA new order was created

order.updatedAn order was updated

product.stock_changedProduct stock changed

variant.stock_changedVariant stock changed

Webhook headers

X-Mobitsa-Event X-Mobitsa-Delivery X-Mobitsa-Timestamp X-Mobitsa-Signature

Temporary failures trigger up to 5 delivery attempts.

One event envelope

{
  "id": "evt_01J…",
  "schema_version": "1",
  "event": "product.stock_changed",
  "occurred_at": "2026-07-27T12:00:00.000000Z",
  "site": {"id": 42},
  "data": {
    "product": {"id": 314, "sku": "SKU-314", "stock": 18},
    "change": {"previous_stock": 20, "stock": 18}
  }
}

Signature verification

The signature is calculated from the exact raw request body. Do not transform JSON before verifying the HMAC SHA-256 value.

$rawBody = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_MOBITSA_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

Integration security

The public reference explains the contract without exposing settings for a specific site.

Minimum permissions

Give each connection only the permissions required by its workflow.

Signed events

Verify HMAC SHA-256 against the exact raw body before processing data.

Idempotent handling

Use the delivery identifier because the same event may arrive more than once.

Connection steps

01
Select a store site
An integration always belongs to one site inside a workspace.
02
Create a connection
Issue an API key, select permissions, and optionally add a webhook URL.
03
Implement the contract
Set up server requests, signature verification, and idempotent event handling.