Overview
Use this checklist before relying on an API integration for daily operations. It covers test data, credentials, failure handling, monitoring and recovery. Your integration runs these processes; Mobaro supplies the public API and, when enabled, webhooks.
At a glance |
|
Who can do this | Integration owners and developers; key creation needs Organization › Administrate |
Where | Your integration; Configuration › API |
Works on | Public API; Backend (web) for setup |
Availability | API access, enabled per organization by Mobaro — ask your CSM |
Prepare a controlled test
1. Confirm the organization and scope
Ask your CSM or Mobaro Support to confirm an appropriate test organization and available features. A new API key does not create a sandbox. Record the organization, integration owner, approved data, supported endpoints and destination before enabling writes.
Use only https://app.mobaro.com/api/customers routes listed in the Developer Hub. A publicly visible schema does not mean every feature is enabled for your organization.
2. Create a dedicated key
In Configuration › API › API Keys, choose Create and give the key a clear integration/environment name. Start with Read-only. Use a separate key without Read-only only for approved write tests. A read-only organization cannot create a write key.
Copy the key into server-side secret storage when it is shown. Send x-api-key on every request. Never put the key in browser code, shared spreadsheets, URLs or logs. See Creating and managing API keys.
⚠️ Heads-up: Keys are organization-wide, not restricted by the creator’s Roles or Locations. A read-only key can still read your organization’s data. Keep test and production configuration distinct and verify the target before each deployment.
3. Prove a small read
GET https://app.mobaro.com/api/customers/locations?Limit=1&Offset=0
x-api-key: YOUR_API_KEY
Check the HTTP status and content type before parsing. Confirm the returned record belongs to the expected organization and that your destination stores its full ID. An empty successful page is different from a failed request. Do not broaden permissions to diagnose an unrelated response.
Test failure and recovery
Test | Expected integration behavior |
More than one page | Fetch every page; Results are capped at 20 per page, most other lists at 128. |
Late upload or later edit | Use the appropriate arrival/change timestamps; see incremental Results sync. |
429 and temporary failure | Use capped backoff with jitter and preserve progress. Simulate failures in your client tests instead of flooding the live API. |
401 / 403 / 404 / invalid input | Stop blind retries; inspect the endpoint, identity, response source and validation message. |
Timeout after a write | Treat the outcome as unknown; reconcile before repeating the operation. |
Restart halfway through a run | Resume or repeat safely from a durable checkpoint without duplicating records. |
Duplicate or out-of-order webhook | Verify signatures, deduplicate, preserve ordering metadata and apply the deletion policy. |
Configuration change | Test key replacement, disabled access and changes to relevant state/field mappings. |
Keep requests below 10 per second per key. User writes share a lower limit; Location Group writes are limited further. Use the current limits in Handling errors, rate limits, and retry logic. Add explicit connect/read or overall timeouts appropriate to your client; do not wait indefinitely.
🛑 Critical: Test creates and updates only on approved records. Deleting a User, Competency or parent Asset can affect related data. Do not use deletion as a generic cleanup step; follow that resource’s documented consequences.
Monitor both ends
4. Record useful integration telemetry
Record run ID, UTC time, operation, resource ID, response status/content type, duration, retry count and last successful checkpoint. Track records read, written, skipped, unresolved and rejected. Redact credentials, cookies and unnecessary personal data.
Set alerts for repeated failures, stalled checkpoints, unexpected empty runs and growing backlogs. Assign an owner and an escalation route. The API Keys table shows key names, prefixes, creation dates and Read-only status; it does not show a last-used timestamp.
5. Inspect failed webhook deliveries
For webhook integrations, use Configuration › API › Webhooks and Webhook Notifications. Open a waiting or failed notification’s details to compare its destination, event and errors with your receiver logs. See Monitoring webhook deliveries for navigation and permissions.
Successful deliveries disappear from this queue. An empty list is not proof your downstream processing succeeded; verify your receiver’s durable records too. Super Users can retry or delete notifications. Fix the receiver before retrying.
⚠️ Heads-up: Disabling a webhook does not cancel notifications already queued. Deleting a notification permanently abandons that delivery. Plan receiver maintenance and recovery using the webhook behavior guide.
Approve the production handover
Compare representative source and destination records, including counts, IDs, states, dates and nulls.
Document the field mappings, owners, polling/event transport, rate limits and recovery steps.
Confirm credentials, feature access, alerts and an on-call owner for the production organization.
Start with a limited scope and observe a complete run before expanding.
Keep a pause procedure. Pausing writes prevents further changes; it does not undo completed writes.
Test key replacement using Replace an integration’s API key and update the credential inventory.
Best practices
Save checkpoints only after destination records are durable.
Keep deployment and configuration versions with each run.
Send Support the sanitized method, public route, UTC timestamp, status, response and correlation ID; never send the key.
Frequently asked questions
Can I see which API keys are still in use?
The Backend API Keys table has no last-used field. Check your integration logs and owners, and contact Mobaro Support if you need usage evidence before retiring a key.
Does creating a test API key create a sandbox?
No. A key connects to its organization. Ask your CSM or Support to confirm an appropriate test organization and feature access before testing writes.
The webhook queue is empty. Has the integration finished?
Not necessarily. Successfully delivered notifications leave the queue. Your receiver must confirm that accepted work was processed and saved; delivery success alone does not prove downstream completion.
Should I retry a POST after a timeout?
Not automatically. The write may already have succeeded. Check the intended record, identity mapping and logs before repeating it; stop for review when the outcome remains uncertain.