Integrations Reference

ArkanPM connects to the rest of your tech stack through two mechanisms: integrations (long-running connectors with their own config) and webhooks (event-driven outbound notifications). This reference covers both.

Integration types

Six first-class integration categories:

Each integration entry has:

• Name, type, endpoint URL
• Credentials (API key / OAuth client / shared secret)
• Sync frequency (real-time via webhook, or scheduled poll)
• Status (enabled / disabled / error)
• Mapping configuration (which ArkanPM entities sync with which external entities)
• Log history

Arkan Handover integration

Purpose-built for the handover moment between the Arkan construction platform (ArkanCM) and the property management platform.

What flows in

• Defects — recorded during construction snagging, flow in as either ArkanPM defect records or work orders (you choose).
• Snagging items — punch list items from pre-handover walk-throughs.
• Warranty records — manufacturer/installer warranties, with policy numbers, start/end dates, provider contacts.

Configuring the integration

1. Sidebar > Admin > Settings > Integrations > Add Integration > Arkan Handover.
2. Shared secret — paste the handshake secret from the construction platform.
3. Building mapping — which ArkanPM building receives the data (either a single target or a rule based on the construction project's metadata).
4. Asset category mapping — as handed-over assets arrive, which ArkanPM category they land in (e.g., "Construction HVAC unit" → "HVAC Equipment").
5. Work order settings — for defects:
   • Auto-create work orders? (yes / no)
   • Default priority
   • Default assignee role or specific user
6. Warranty settings — warranty records land on the corresponding asset's Warranty tab, with full claim workflow enabled.
7. Enable. Once enabled, records stream in as they're created on the construction side.

Verifying data flow

Check the Integration Log tab daily during initial rollout. Every record shows:

• Timestamp received
• Source construction record ID
• Target ArkanPM record ID
• Status (success / mapped / error)
• Error message if any

Errors typically indicate a mapping gap — e.g., an asset category referenced on the construction side doesn't exist on the FM side yet. Add the missing category and use Retry Failed to replay.

ERP integration

Typical use

• Post maintenance costs as journal entries
• Map buildings to cost centers
• Push vendor invoices for AP processing
• Pull chart of accounts for GL coding

Configuration

1. Add integration, type ERP.
2. Provide API endpoint and credentials.
3. Field mapping — map ArkanPM fields to ERP fields (building → cost center, WO cost → expense account, vendor → supplier).
4. Sync schedule — real-time (webhook-driven) or nightly batch.
5. Posting rules — when does data post? On WO close? On WO verify? On month-end?
6. Test, enable.

Accounting integration

Typical use

• Create invoices when work orders close (charging to landlords or residents)
• Sync vendor invoices back from accounting for reconciliation
• Push rent collection events

Configuration

Similar to ERP but scoped to invoicing. Key config:

• Invoice numbering format
• Invoice template
• Tax handling (VAT / no-VAT)
• Payment terms
• Currency

BMS (Building Management System) integration

Typical use

• Receive fault alarms from HVAC, fire, or elevator systems → auto-create Emergency WOs
• Pull occupancy data from access-control systems
• Feed asset health from BMS sensors

Supported protocols

ArkanPM can integrate via:

• REST APIs (most modern BMS)
• Webhook push from BMS
• MQTT subscription (for some IoT-bridged BMS)
• Custom adapters (via the Custom integration type)

Configure the protocol-specific settings in the integration's config panel.

IoT integration

Typical use

• Occupancy sensors → occupancy dashboard
• Leak detectors → auto-create Emergency WOs when water is detected
• Air-quality sensors → trend charts on asset detail pages
• Energy meters → continuous meter readings on the Asset's Meter tab

Configuration

Each IoT device maps to an asset in ArkanPM. Readings stream in via webhook or poll and attach to that asset's readings history.

Custom integration

For anything not covered by the categories above. Provides:

• Generic webhook receiver endpoints
• API key-based authentication
• Flexible field mapping
• Full log visibility

Use this for partner integrations, one-off bespoke tools, or internal scripts.

Webhooks (outbound)

When ArkanPM events happen, webhooks notify external systems in near real-time.

Event catalog

Available events to subscribe to (subset — full list in Sidebar > Admin > Settings > Webhooks > Event Catalog):

Work Orders

• work_order.created
• work_order.assigned
• work_order.started
• work_order.on_hold
• work_order.resumed
• work_order.completed
• work_order.verified
• work_order.closed
• work_order.sla_breached

Leases

• lease.created
• lease.activated
• lease.renewed
• lease.expiring_soon (30/60/90-day thresholds)
• lease.terminated

Inspections

• inspection.scheduled
• inspection.started
• inspection.submitted
• inspection.approved
• inspection.rejected
• inspection.failed_item

Compliance

• certificate.added
• certificate.expiring_soon
• certificate.expired

Assets

• asset.created
• asset.condition_changed
• asset.transferred
• asset.disposed
• asset.warranty_expiring

Resident events

• work_request.submitted
• booking.created
• booking.cancelled
• visitor_pass.created
• visitor_pass.checked_in
• visitor_pass.checked_out
• announcement.acknowledged

Webhook payload shape

Every payload is JSON with this envelope:

{
  "event": "work_order.completed",
  "event_id": "evt_01H8X...",
  "timestamp": "2026-04-12T18:45:23Z",
  "tenant_id": "tnt_7GQ...",
  "data": {
    "work_order": {
      "id": "wo_9TP...",
      "number": "WO-2026-00147",
      "title": "Leaking bathroom faucet — Unit 1504",
      "status": "completed",
      "priority": "medium",
      "building": { "id": "bld_...", "name": "Tower A" },
      "unit": { "id": "unt_...", "name": "1504" },
      "completed_at": "2026-04-12T18:45:23Z",
      "completed_by": { "id": "usr_...", "name": "Ahmed Khaled" },
      "resolution_notes": "Replaced shower valve cartridge...",
      "sla": { "response": "met", "resolution": "met" }
    }
  }
}

Signature verification

Every webhook request includes an X-ArkanPM-Signature header. Verify it:

1. Compute HMAC-SHA256 of the raw request body, using your webhook's shared secret as the key.
2. Compare to the signature header (hex-encoded).
3. If it doesn't match, reject the request.

Example (Node.js):

import crypto from "crypto";

const secret = process.env.ARKANPM_WEBHOOK_SECRET;
const signature = req.header("X-ArkanPM-Signature");
const payload = req.rawBody; // the unparsed request body as string

const expected = crypto
  .createHmac("sha256", secret)
  .update(payload)
  .digest("hex");

if (signature !== expected) {
  return res.status(401).send("Bad signature");
}

// ...handle the event

Retry policy

• Default: 5 retries with exponential backoff (1s, 4s, 16s, 1min, 5min).
• Configurable per webhook.
• After all retries are exhausted, the delivery is marked failed and an alert fires to admins.

Idempotency

Every webhook request includes an event_id. Use it to deduplicate on your side — if you receive the same event_id twice (from a retry), process it once.

API access

For programmatic access beyond webhooks, ArkanPM provides a REST API.

• Authentication: Bearer token (issued per API key)
• Base URL: https://api.<your-tenant>.arkanpm.com
• Swagger docs: available inside the platform at Sidebar > Admin > Settings > API Docs
• Rate limits: per API key, configurable per plan

The API mirrors the webhook event model — you can poll for anything a webhook can push. Use webhooks for real-time use cases and the API for snapshots, backfills, and bespoke queries.

Troubleshooting integrations

Integration shows "Error" status

1. Open the integration's Log tab.
2. Find the most recent failed call.
3. Read the error message — most point directly at the problem (expired credential, unreachable endpoint, schema mismatch).
4. Fix the underlying cause.
5. Click Retry Failed to replay queued failures.

Webhook deliveries all failing

1. Verify your endpoint is reachable from the public internet (ArkanPM pushes, it doesn't tunnel).
2. Check your signature verification — the most common cause of all-failing webhooks is a mismatched secret or body encoding.
3. Check your SSL certificate — ArkanPM requires valid TLS.
4. Check your endpoint's response time — exceeding the timeout fails the delivery.

Arkan Handover data not flowing

1. Confirm the construction side is publishing. Ask them to check their outbound queue.
2. Confirm the shared secret matches.
3. Check the integration log for "rejected" entries — typically mapping gaps.

Related:

• Admin Handbook → — how to configure integrations and webhooks
• Security & Audit → — signing secrets, API key rotation