Developer API, Webhooks & Connector SDK — OpsIQ

Developer API, Webhooks & Connector SDK — OpsIQ

Build AI-aware integrations with the OpsIQ Developer API, which includes signed REST endpoints, HMAC webhooks, action contracts, and SDKs for PHP, Node, and Python. Get a key for free and make your platform AI-operable.

Overview

OpsIQ exposes a clean REST API, HMAC-signed webhooks, an action-contract registry, and ready-to-ship SDKs. You can define what events fire from your system, what actions the AI is allowed to run, and what data is safe to read. OpsIQ handles signatures, retries, audit logs, and confirmation flows for you.

Getting Started

1. Get an API key: Sign up and generate a scoped public/secret key pair in developer settings. Give each integration only the surfaces it needs.
2. Fire & subscribe: POST a signed event to the events/fire endpoint (or use an SDK), then point any URL at any event — signed, with a delivery ID and back-off retries.
3. Register an action: Declare a signed action contract so the AI can safely run operations, including role checks, confirmation policy, and a full audit trail.

Event Handling

Tell OpsIQ what just happened by firing universal events from your platform or your own custom event names. Every subscriber reacts in real time, in priority order.

Event Reference

• Universal events: invoice.paid, ticket.created, subscription.cancelled, customer.signed_up, or your own custom events.

Action Contracts

Tell OpsIQ what the AI is allowed to do. An action contract is a signed JSON declaration that specifies what the action does, which roles can run it, what parameters it accepts, whether confirmation is required, and the endpoint to call.

Action Schema Example

{
    "key": "saas.refund_invoice",
    "label": "Refund a paid invoice",
    "surface": ["admin"],
    "roles": ["owner", "billing_admin"],
    "requires_confirmation": true,
    "params": {
        "invoice_id": {
            "type": "int",
            "required": true
        },
        "reason": {
            "type": "string",
            "max": 500
        }
    },
    "endpoint": "https://api.you.com/refund",
    "audit": true
}

Webhooks

Push events to your stack with cryptographic proof. Subscribe any URL to any event. OpsIQ POSTs the JSON payload signed with HMAC-SHA256 over the raw body, which you can verify in a few lines.

Webhook Reference

$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_OPSIQ_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $sig)) http_response_code(401);
$event = json_decode($raw, true);

SDKs

Three official SDKs handle authentication, signing, retries, idempotency keys, and typed responses. Alternatively, you can stay framework-free, as every SDK is a thin wrapper around the same REST surface.

Client Examples

import { OpsIQ } from "@opsiq/sdk";
const ops = new OpsIQ({ publicKey, secretKey });
await ops.events.fire("order.shipped", { customer_id: 421, order_ref: "NB-9182", carrier: "DHL" });
const result = await ops.actions.run("saas.send_kb_link", { ticket_id: 5519, article: "how-to-reset-password" });

Connector Pattern

A connector is a folder with one PHP class. OpsIQ discovers it, the registry wires the events, and your platform-specific code stays cleanly separated from the core.

Connector Guide

1. Scaffold a folder with connector.php extending AbstractConnector.
2. Declare actions.json and settings.json manifests.
3. Implement identity, context, and webhook providers.
4. Subscribe to the events you care about.
5. Sign it, drop it in, and enable it in admin.

Testing

Every workspace exposes a sandbox with its own key pair that hits the same API surface without touching production data. Use POST /v1/webhooks/test to fire a signed sample delivery at your endpoint and confirm your signature verification before going live.

FAQ

How does authentication work?

Every request carries your public key plus an X-OpsIQ-Signature header, which is an HMAC-SHA256 of the raw body using your secret key, and an X-OpsIQ-Timestamp for replay protection. OpsIQ verifies the signature, the timestamp window, your key scope, and the actor's role before anything runs.

Can the AI run actions I haven't approved?

No. The AI can only propose actions that exist in your action-contract registry. It cannot invent a call.

How do I verify a webhook is really from OpsIQ?

Recompute sha256=hash_hmac('sha256', $rawBody, $secret) and compare it to the X-OpsIQ-Signature header with a constant-time check (hash_equals).

Which SDKs are available?

Official SDKs for PHP 8.4+, Node.js 18+, and Python 3.10+ handle signing, retries, idempotency keys, and typed responses.

Can I test without touching production?

Yes. Every workspace exposes a sandbox with its own key pair that hits the same API surface without touching production data.

Does the self-hosted edition behave the same as cloud?

Yes. Self-hosted installs run the identical code path, so there's no behavioral drift between cloud and on-prem.

What's a connector, exactly?

A connector is a self-contained folder with one PHP class extending AbstractConnector, plus actions.json and settings.json manifests. You implement identityProviders(), contextProviders(), registerActions(), subscribers(), and handleWebhook.

Related articles

• OpsIQ Developer Documentation