Developer Area — API Keys & Webhooks

Summary The developer area (under Integrations) is where you connect MKController to your own systems. Two building blocks: API keys — a secret you send with each request to authenticate calls to the MKController API; and webhooks — an HTTPS endpoint of yours that MKController calls with a JSON payload whenever an event happens, plus a delivery history so you can see and replay what was sent.

An API key authenticates your requests as your company. Anyone holding it can act on your account — treat it like a password.

1. Open Integrations → APIs.
2. On the Keys tab, click Create key.
3. Give it a name (e.g. Billing sync) and confirm.
4. Copy the key now — it is shown only once. Store it in your server’s secret manager, never in front-end code or a public repo.

Using the key. Send it in the HTTP Authorization header on every request:

curl https://app.mkcontroller.com/app/mkcontroller-server/rest/… \
  -H "Authorization: Bearer <YOUR_API_KEY>"

• Keys are per company; create separate keys per integration so you can revoke one without breaking the others.
• Rotate a key by creating a new one, switching your integration over, then revoking the old one.
• The Logs tab shows recent requests made with your keys — handy for debugging auth or spotting unexpected traffic.

A webhook lets MKController push events to you (instead of you polling). On each event we POST a JSON snapshot to your URL.

1. Open Integrations → Webhooks.
2. On the Register tab, click Add webhook.
3. Enter a Name and your endpoint URL — it must be HTTPS and publicly reachable.
4. Save. Toggle the webhook on/off any time from the list.

What your endpoint receives. A POST with a JSON body describing the event (the entity and a snapshot of its state). Your endpoint should:

• Respond quickly with a 2xx status to acknowledge receipt (do heavy work asynchronously).
• Be idempotent — the same event may be delivered more than once (retries).
• Ignore fields it doesn’t recognise, so new fields don’t break you.

Where webhooks fire. Beyond the company-level webhooks here, a voucher can opt in to your company webhooks on its Integrations tab, so hotspot guest events (connections, payments) reach your endpoint per voucher.

Every call MKController makes to your endpoint is recorded so you can audit and debug it.

1. Open Integrations → Webhooks → History.
2. Each row shows the status (2xx = accepted, others = failed), the time, the target webhook, and a preview of the request/response.
3. Click a row to inspect the full payload we sent and the response we got back.
4. Use Resend to replay a delivery while you fix your endpoint — no guest action needed.

Common history states:

• 2xx — your endpoint accepted the event. Done.
• 4xx / 5xx — your endpoint rejected or errored; check the response preview, fix, and Resend.
• No response / timeout — the URL was unreachable or too slow; confirm it’s public HTTPS and answers within a few seconds.

• Secret hygiene: API keys live server-side only; rotate on staff changes; one key per integration.
• Verify the source: only trust webhook calls on your own secret path/URL; don’t act on data from an unexpected caller.
• Fail safe: queue incoming webhooks and process them off the request thread so a slow job never causes a timeout (and a retry storm).

Need a hand? Talk to our team on WhatsApp or start your free MKController account.