> For the complete documentation index, see [llms.txt](https://developers.share.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.share.inc/splynx/connect-your-splynx.md). # Connect your Splynx Share integrates with **your own Splynx instance**: you give Share API access to your Splynx, and Share gives you a webhook endpoint to configure on your side. Once both directions are connected, Share mirrors subscribers, services, plans, and installation tasks into your Splynx automatically, and edits made by your CSR team in Splynx flow back to Share. Payment and finance data is **not** mirrored in either direction — Share owns payments end-to-end and never touches your Splynx finance module. This page is the end-to-end setup guide. It assumes you operate your own Splynx instance and have an administrator account on it. ## Prerequisites * A Splynx instance reachable over **HTTPS** with a valid certificate. Share's platform connects to it from the public internet — if your instance sits behind a firewall, allowlist Share's egress IPs (your account manager will provide them). * An administrator account on your Splynx with access to **System → Administration → API keys** and **Config → Integrations → Hooks**. * Access to the Share partner portal (or an active line to your Share account manager, who can run the setup for you). ## Step 1 — Create an API key on your Splynx In your Splynx admin UI, go to **System → Administration → API keys** and create a new key for Share. In the key's permissions tree, grant the following (section and permission names as they appear in the Splynx UI): | Section | Permission | Actions | Why | | ---------------- | ----------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Config** | Additional fields | Add, View, Update, Delete | One-time setup: register the Share-managed fields (see Step 3) | | **Config** | Scheduling project workflows | Add, View, Update, Delete | One-time setup: create the Share Installations workflow | | **Config** | Scheduling project types | Add, View, Update, Delete | One-time setup: create the Share Installations project type | | **Config** | Scheduling project categories | Add, View, Update, Delete | One-time setup: create the Share Installations project category | | **Tariff plans** | Internet | Add, View, Update, Delete | Plan sync — Share creates and updates tariffs to mirror your Share plans | | **Customers** | Customer | Add, View, Update, Delete | Mirror Share subscribers into your Splynx | | **Customers** | Customer billing | View, Update | Disable Splynx's own billing engine on Share-managed customers — prevents Splynx from auto-blocking for a low balance | | **Customers** | Customer notes | Add, View, Delete | Pin a note on the customer when Share quarantines it (e.g. duplicate phone) so your CSR team sees why | | **Customers** | Customer internet services | Add, View, Update, Delete | Create services, reassign tariffs, flip service status on suspension | | **Scheduling** | Projects | Add, View, Update, Delete, Options | Maintain the "Share Installations" project | | **Scheduling** | Tasks | Add, View, Update, Delete, Options | Create and cancel installation tasks | | **Networking** | IPv4 networks | View | Resolve the pool name when a customer's service is assigned a dynamic IPv4 pool | > The three **Config → Scheduling …** entries are easy to miss: the workflow, project type, and project category permissions live under the **Config** section of the tree, not under **Scheduling**. If any of the three is left ungranted, registration fails partway with a Splynx "Call forbidden!" error. ### Additional permission for bulk migration The permissions above cover day-to-day operation. A **one-time bulk migration** of static-IP subscribers into Share (run from the platform-admin migration console, the `ensure_networks` step) also has to **create IPv4 networks** in your Splynx so the imported static IPs have a pool to live in. For that, grant the integration key one extra permission: | Section | Item | Access rights | Why | | -------------- | ------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Networking** | IPv4 networks | Add | Create the IPv4 network pools the imported static IPs need (the base **View** grant above lets the step list existing networks and skip ones that already exist). | If this is missing, the `ensure_networks` step stops with a Splynx `403 "Call forbidden!"` and the console prints an actionable message. You can either grant **Networking → IPv4 networks** Add to the key and re-run the step, or pre-create the required networks by hand in the Splynx UI (**Networking → IPv4 Networks → Add**) and re-run — the step is idempotent and skips networks that already exist. Once the bulk migration is done, this permission can be narrowed back to **View** if you prefer. Note the **API key** and **API secret** — you'll hand both to Share in the next step. Treat the secret like a password; Share stores it encrypted and never displays it back. ## Step 2 — Register the integration with Share In the Share partner portal, open **Integrations → Splynx** and enter: * your Splynx instance URL (e.g. `https://your-company-name.splynx.app`) * the API key and secret from Step 1 Share validates the credentials by authenticating against your instance before saving — a typo in the key, an unreachable host, or a plain-HTTP URL is rejected immediately with a specific error. You don't need to wait for that to succeed to get your webhook values, though. As soon as you open **Integrations → Splynx**, the portal shows two values you'll need in Step 4 — Share issues them the first time you view the page, even before you've entered any credentials: * **Your webhook URL** — unique to your integration, in the form `https://api.share.inc/v1/integrations/splynx//webhooks` * **Your webhook secret** — used to sign every event your Splynx sends to Share Both are stable for the life of the integration: registering or later updating your API credentials never changes them, so you only configure your Splynx hook once. Because they don't depend on Step 1–2 completing, you can do Step 4 first if that's more convenient — for example, to hand the webhook URL and secret to a colleague who manages your Splynx hooks while you're still gathering the API key. > If you prefer not to use the portal, your Share account manager can register the integration for you — you supply the same three values and receive the same webhook URL and secret back. ## Step 3 — What Share sets up on your instance Immediately after registration, Share bootstraps your instance. No action is needed from you, but your Splynx audit log will show these writes from Share's API key: * **Tariff additional field** — `installation_fee`, registered on the *Internet tariffs* module. This lets a Share plan carry its installation pricing onto the mirrored tariff. * **Internet-service additional fields** — registered on the *Internet services* module: `installation_required`, `installation_free`, `installation_paid`, `cycle_paid`. These carry installation and billing state on each service so your CSR team sees it in the Splynx UI. `installation_paid` and `cycle_paid` are registered **read-only**: Share maintains them as payment status flows through the platform — your team sees them but cannot edit them. * **Share price** (`share_price`) — a read-only field on the *Internet services* module that shows the real plan price for each Share-managed service. The chargeable service price itself is kept at **0** on purpose: Share handles billing, so Splynx's own billing engine must never block a Share customer for a low balance. The **Share price** column is display-only so your team can still see what the subscriber is paying. * **The "Share Installations" scheduling project** — with a workflow (*To Do / Scheduled / In Progress / Done / Cancelled*), project type, and category. Share creates installation tasks here; see [Installations and Splynx tasks](/splynx/installations-and-tasks.md). The bootstrap is idempotent — re-registering or updating credentials re-checks everything and repairs drift without duplicating anything. ## Step 4 — Configure the hook on your Splynx In your Splynx admin UI, go to **Config → Integrations → Hooks** and create a single hook with: * **URL**: your webhook URL from Step 2 * **Secret**: your webhook secret from Step 2 * **Events**: select the following from the event list: | Splynx event | What it drives in Share | | ------------------------ | --------------------------------------------------------------------------------------------------------------- | | `customer.create` | Mirrors a new Splynx customer into Share as a subscriber | | `customer.edit` | Profile updates (name / email / phone / address), credential changes, and status transitions (active ↔ blocked) | | `customer.delete` | Deactivates the Share subscriber and its billing | | `service.create` | Provisions the matching Share subscription and network credentials | | `service.edit` | Tariff change or per-service override on an existing internet service | | `service.delete` | Winds down the matching Share subscription | | `tariff.delete` | Soft-disables the mapped Share plan | | `scheduling_task.create` | Acknowledged only — Share owns task creation; subscribing prevents Splynx-side delivery retries | | `scheduling_task.edit` | Installation task moved to Done / Cancelled — advances the installation in Share | | `scheduling_task.delete` | Acknowledged only, same as create | In the same hook form, Splynx shows a **permissions tree** for the hook — this is separate from the event list and controls what the hook is authorised to deliver. Grant the following: | Section | Permissions to enable | | --------------------- | ----------------------------------------------------------------------- | | **Customers info** | Edit customers info | | **Customers** | Create customer, Edit customer, Delete customer | | **Internet services** | Create internet service, Edit internet service, Delete internet service | | **Task** | Add task, Edit task, Delete task, Archive task, Restore task | | **Link task** | Link task, Unlink task | When you save, Splynx sends a reachability ping to the URL. Share answers it immediately — if Splynx reports the URL as unreachable, check that the URL was pasted completely (it contains a long token) and that your network allows outbound HTTPS to `api.share.inc`. > **Do not subscribe `payment` events.** Payment and finance data never crosses the integration — Share is the source of truth for payments, and an inbound payment event would describe a manual Splynx-side entry Share does not own and cannot act on safely. Likewise, leave `tariff.create` and `tariff.edit` unselected: Share is the source of truth for plans, and those events are rejected as unsupported. Every event your Splynx sends is signed with HMAC-SHA1 using your webhook secret; Share verifies the signature before processing and rejects anything unsigned or mis-signed. ## Step 5 — Verify the connection Back in the Share portal, **Integrations → Splynx** shows two independent health indicators: * **API connection** — whether Share can authenticate against your instance. *Connected* means outbound sync (Share → Splynx) is working. * **Webhooks** — the timestamp of the last event received from your Splynx. After Step 4, trigger a test event (edit any test customer's name in Splynx) and refresh: the timestamp should update within seconds. This confirms inbound sync (Splynx → Share). Both green? You're connected. Subscribers, plans, and services now flow per the tables in the [integration overview](/splynx/splynx.md). ## Maintenance * **Rotating your API key.** Create the new key in Splynx first, then update the credentials in the Share portal (or via your account manager), then delete the old key. Updating credentials never changes your webhook URL or secret — no hook reconfiguration needed. * **Rotating the webhook secret.** Not currently self-serve — contact your account manager, and coordinate the change on both sides to avoid a window of rejected events. * **Moving your Splynx to a new URL.** Update the instance URL in the Share portal credentials form. Your webhook URL on the Share side is unaffected, but remember the hook configuration lives in your Splynx — it migrates with your instance data. ## Troubleshooting | Symptom | Likely cause and fix | | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | | Registration rejected: *invalid credentials* | API key/secret typo, or the key lacks login permission. Re-copy from Splynx. | | Registration rejected: *unreachable* | Firewall blocking Share's egress IPs, DNS not public, or self-signed certificate. | | Hook ping fails on save | Webhook URL truncated (the token is long), or outbound HTTPS from your Splynx host is blocked. | | API pill *Connected* but webhook timestamp stale | Hook misconfigured or disabled on your side — re-check Step 4, then trigger a test edit. | | Events arrive but changes don't appear in Share | Signature mismatch — the hook secret in Splynx doesn't match the one issued in Step 2. Re-paste the secret. | Still stuck? Your account manager can trace any individual event end-to-end — note the approximate time and the customer affected.