Help center / Guide 13

api, webhooks& custom fields

Connect Simbako ERP to the rest of your stack, safely.

API tokens

  1. Open My account → API Tokens (needs the API access permission).
  2. Name the token, choose its scopes and how many days it lasts (up to 90).
  3. Copy the token now. It's shown once and stored only as a hash. Lost it? Revoke it and create a new one.

A token can never do more than you can: you can only choose scopes your roles allow, and if your access is reduced or your account is deactivated, the token stops working too.

Scope Lets the token read Needs permission
contacts:read Contacts Contacts: view
products:read Products and stock on hand Inventory: view
invoices:read Invoices and bills Invoicing: view

Using the API

Send the token as a bearer token over HTTPS:

GET https://simbako.onlypabs.com/api/v1/contacts?per_page=50&page=1
Authorization: Bearer YOUR_TOKEN
Accept: application/json
  • Endpoints: /api/v1/contacts, /api/v1/products, /api/v1/invoices.
  • Results are paginated: per_page from 1 to 100 (default 25) and page.
  • Each response lists only documented fields, never internal ones.
  • Limit: 60 requests per minute per token. Above that you get 429 Too Many Requests; wait and retry.
  • The API follows your workspace's rules: if the app is switched off, your subscription has lapsed or the caller's address isn't on your IP allowlist, requests are refused.

Webhooks

Webhooks tell your other systems when something happens in Simbako ERP.

  1. Integrations → Webhooks → New webhook: a public https:// address and the events you want.
  2. Each webhook gets its own signing secret. Rotate it any time; Test sends a sample delivery.

Available events: contact.created, lead.won, sales_order.confirmed, invoice.posted, ticket.created, web_order.created, event.registered, applicant.created.

Each delivery is a JSON POST:

{
  "id": "unique delivery id",
  "event": "invoice.posted",
  "occurred_at": "2026-10-09T08:15:00+00:00",
  "data": { … the record … }
}

Verify the signature

Every delivery carries X-Simbako-Event and X-Simbako-Signature: t=<unix time>,v1=<hex>. To check it:

  1. Read t and v1 from the header.
  2. Compute HMAC-SHA256 of t + "." + raw request body using your signing secret.
  3. Compare it with v1 using a constant-time comparison, and reject deliveries whose t is more than 5 minutes old.

Use the id to ignore duplicates. For safety, webhooks can't point at private, loopback or internal network addresses.

IoT readings

  1. IoT Devices → New device: name, unit, optional alert range and linked equipment. Copy the device key (shown once; Rotate to replace it).
  2. The device sends readings over HTTPS:
POST https://simbako.onlypabs.com/api/iot/readings
Authorization: Bearer DEVICE_KEY
Content-Type: application/json

{"value": 21.7, "recorded_at": "2026-10-09T08:15:00Z"}

recorded_at is optional (now by default) and may be up to 7 days old. A reading outside the alert range opens a high-priority maintenance request on the linked equipment.

Custom fields

With Custom Fields you can add your own fields to contacts, products, CRM leads, employees, projects, helpdesk tickets, vehicles and equipment. Field types: text, number, date, choice list and checkbox, optionally required. They appear on the record's form straight away.