Plateforme de développement · REST · webhooks · SDKs

Rendez votre plateforme exploitable par l’IA.

OpsIQ expose une API REST propre, des webhooks signés HMAC, un registre de contrats d'action et des SDK prêts à expédier. Définissez quels événements se déclenchent depuis votre système, quelles actions l'IA est autorisée à exécuter, et quelles données sont sûres à lire. OpsIQ gère les signatures, les réessais, les journaux d'audit et les flux de confirmation pour vous.

Obtenez une clé API Lisez la documentation SDK sur GitHub

HMAC-SHA256 dans les deux sensSDKs PHP · Node · PythonContrat OpenAPI 3.0.3couverture d'audit à 100%

Demande signée dans

Webhook signé sortant → 200 OK

En direct

3SDK officiels : PHP, Node, Python

HMACSHA-256 signé à chaque requête

40+événements universels à s'abonner

100%couverture du journal d'audit sur les actions

Le cycle de vie de la demande

Demande en cours. Webhook signé sortant.

Vous POSTez à l'API OpsIQ avec votre clé Bearer ciblée. OpsIQ vérifie la portée et le rôle, exécute l'action contractée, écrit une ligne d'audit - puis envoie un webhook signé HMAC à votre point de terminaison. Chaque saut est authentifié, idempotent et réessayé en cas d'échec.

webhooks HMAC-SHA256 - les charges utiles des webhooks entrants et sortants sont signées sur le corps brut ; les appels API s'authentifient avec une clé Bearer limitée.

Réessais automatiques - les livraisons échouées se retirent et réessaient, avec un ID de livraison que vous pouvez tracer.

Clés d'idempotence - sûr à rejouer par conception, donc une livraison réessayée n'agit jamais deux fois.

01 demande signée 02 vérifier HMAC 03 exécuter le contrat 04 écrire une ligne d ' audit 05 webhook signé

Démarrage rapide

D'un zéro à une intégration en direct en quatre étapes.

Générez une clé, déclenchez votre premier événement, abonnez un webhook, enregistrez une action. Vous pouvez exécuter l'ensemble de la boucle contre le bac à sable avant de toucher aux données de production.

Console SandboxConnecté

PromouvoirSandbox → production, même code

Obtenez une clé

Inscrivez-vous et générez une clé API Bearer limitée (opq_…) dans les paramètres développeur, et donnez à chaque intégration uniquement les surfaces dont elle a besoin.

Activer et s'abonner

POST un signé events/fire (ou utilisez un SDK), puis pointez n'importe quelle URL vers n'importe quel événement, signé, avec un ID de livraison et des tentatives de reprise.

Enregistrer une action

Déclarez un contrat d'action signé afin que l'IA puisse exécuter des opérations en toute sécurité, avec des vérifications de rôle, une politique de confirmation et une piste d'audit complète.

Comment cela s'assemble

Un modèle de connecteur. Cinq primitives propres.

Tout ce qui est spécifique à la plateforme vit dans un connecteur. Le cœur d'OpsIQ reste générique, l'IA reste prévisible, et votre intégration reste auditable.

Déclencheurs

Dites à OpsIQ ce qui vient de se passer.

Déclenchez des événements universels depuis votre plateforme - ou vos propres noms d'événements personnalisés. Chaque abonné réagit en temps réel, par ordre de priorité.

Référence d'événement

Événements universels + personnalisésinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up ou votre propre. Abonnés en fan-outLe cerveau AI, les règles d'automatisation, les connecteurs miroir et vos points de terminaison webhook réagissent tous. Ordre de prioritéDispatch déterministe afin que les miroirs écrivent avant que les alertes ne se déclenchent.

02 / Contrats d'action

Dites à OpsIQ ce que l'IA est autorisée à faire.

Un contrat d'action est une déclaration JSON signée : ce que fait l'action, quels rôles peuvent l'exécuter, quels paramètres elle accepte, si une confirmation est requise, et le point de terminaison à appeler.

Schéma d ' action

L'IA ne peut pas inventer d'actionsIl ne peut demander d'exécuter que ceux que vous avez enregistrés. Politique de confirmationLes actions risquées déclenchent une carte d'aperçu avant tout effet secondaire. Gating par rôle + surfaceChaque action déclare les rôles et surfaces autorisés à l'exécuter.

contrat d'action - JSON

{
  "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
}

14. Changements

Poussez des événements vers votre pile - avec preuve cryptographique.

Abonnez n'importe quelle URL à n'importe quel événement. OpsIQ POSTe la charge JSON signée avec HMAC-SHA256 sur le corps brut - vérifiez-le en quelques lignes.

Protection contre la relectureID de livraison traçableRetraits de backoff

Référence Webhook

vérifier le webhook - php

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

04 / SDKs

Clients intégrables pour la langue que vous utilisez déjà.

Trois SDK officiels gèrent l'authentification, la signature, les réessais, les clés d'idempotence et les réponses typées. Ou restez sans cadre - chaque SDK est un mince wrapper autour de la même surface REST.

exemples de clients

import { OpsIQ } from "@opsiq/sdk";
const ops = new OpsIQ({ apiKey: process.env.OPSIQ_KEY });

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"
});

use OpsIQ\Client;

$ops = new Client([
  'api_key' => getenv('OPSIQ_KEY'),
]);

$ops->events->fire('order.shipped', [
  'customer_id' => 421,
  'order_ref' => 'NB-9182',
]);

$result = $ops->actions->run('saas.send_kb_link', [
  'ticket_id' => 5519,
  'article' => 'how-to-reset-password',
]);

from opsiq import OpsIQ

ops = OpsIQ(
    api_key=os.environ["OPSIQ_KEY"],
)

ops.events.fire("order.shipped", {
    "customer_id": 421,
    "order_ref": "NB-9182",
})

result = ops.actions.run("saas.send_kb_link", {
    "ticket_id": 5519,
    "article": "how-to-reset-password",
})

PHP 8.4+NodeJS18+Python 3.10+OpenAPI3.0.3

05 / Le modèle de connecteur

Construisez une fois. Branchez-vous à tout.

Un connecteur est un dossier avec une classe PHP. OpsIQ le découvre, le registre connecte les événements, et votre code spécifique à la plateforme reste proprement séparé du cœur.

Guide du connecteur

Cinq hooksidentityProviders(), contextProviders(), registerActions(), subscribers(), handleWebhook(). Piloté par manifesteactions.json et settings.json déclarer des contrats et des configurations. Découvert automatiquementDéposez le dossier, signez-le, activez-le dans l'administration.

De l'intention à l'action sécurisée

Anglais simple. Opération audité sortie.

OpsIQ n'invente jamais le bon appel. Il parcourt les contrats enregistrés, prépare la charge utile, demande confirmation lorsque l'action l'exige, et produit une ligne d'audit complète lorsqu'il exécute, donc une IA qui peut agir ne devient jamais une IA à laquelle vous ne pouvez pas faire confiance.

Lié par contrat. L'IA ne propose que des actions que vous avez enregistrées.

Confirmer avant les effets secondaires. Les actions risquées affichent d'abord une carte d'aperçu.

Un souvenir total. Chaque invite, réponse et résultat d'action capturé dans l'historique AI.

Voir le schéma d'action

4 étapesintention → audit

HMACsigné avant exécution

Pas d'appels inventésregistre de contrat uniquement

Confirmé par porteaperçu avant effets secondaires

100 % auditéinvite + réponse + résultat

Référence

Surface API en un coup d ' œil.

Chaque point de terminaison principal, son authentification, son idempotence et sa limite de taux par clé. Le contrat complet lisible par machine se trouve dans la référence OpenAPI 3.0.3.

Référence OpenAPI 3.0.3

Point de terminaisonAuthImpotentLimite de taux

ÉcrireEffets secondaires signés

POST /v1/events/fireHMACOui1000 / min

POST /v1/actions/runHMACOui200 / min

POST /v1/webhooks/testHMACOui60 / min

LireContexte, tickets et inventaire de connecteurs

GET /v1/customers/{id}HMACOui2000 / min

GET /v1/ticketsHMACOui2000 / min

GET /v1/connectorsHMACOui2000 / min

Les limites de taux sont par clé et retournées à chaque réponse sous forme de X-OpsIQ-RateLimit-Remaining; dépasser une limite renvoie 429 avec un Retry-After en-tête. Le contrat complet lisible par machine (chaque point de terminaison, schéma et erreur) se trouve dans le Référence OpenAPI 3.0.3.

Construisez un connecteur

Expédier un connecteur dans cinq étapes.

Un connecteur est un dossier autonome. OpsIQ le découvre, le registre relie les événements, et votre code spécifique à la plateforme ne fuit jamais dans le noyau.

1Échafauder un dossier avec connector.php prolongement AbstractConnector.

2Déclarer actions.json et settings.json manifeste.

3Implémentez des fournisseurs d'identité, de contexte et de webhook.

4Abonnez-vous aux événements qui vous intéressent.

5Signez-le, déposez-le, activez-le dans l'administration.

Testez avant de déployer

Une clé sandbox et un testeur de webhook.

Chaque espace de travail expose un sandbox : une clé séparée qui touche la même surface API sans toucher aux données de production. Utilisez POST /v1/webhooks/test pour déclencher une livraison d'échantillon signé à votre point de terminaison et confirmer votre vérification de signature avant de passer en production. Les installations auto-hébergées exécutent le même chemin de code, sans dérive comportementale entre le cloud et sur site.

Clés Sandbox Testeur de webhook Travaux pilotés par Cron Parité Cloud & auto-hébergé

Guide du connecteur Référence Webhook

connector. php · php

classe AcmeConnector étend AbstractConnector { fonction publique clé(): chaîne { retour acme; } // Résoudre qui est l'acteur fonction publique identityProviders(): tableau { retour [nouveau AcmeIdentityProvider()]; } // Alimentez des données en direct dans l'invite IA fonction publique contextProviders(): tableau { retour [nouveau AcmeContextProvider()]; } // Réagir aux événements OpsIQ fonction publique abonnés(): tableau { retour ['invoice. paid' => [nouveau BillingMirror()]]; } // Recevoir des webhooks entrants d'Acme fonction publique handleWebhook(tableau $body): vide { /* … */ } }

⚖️ Comment cela se compare

OpsIQ vs un Intégration DIY.

Ce qu'une plateforme liée par contrat, signée et auditée vous offre que la création de vos propres webhooks et l'intégration des actions IA ne pourront jamais fournir.

Capacité	Créez le vôtre	OpsIQ
HMAC-signed requests & webhooks (both ways)	Hand-rolled	✓
Idempotency keys + replay protection	DIY	✓
Automatic back-off retries with delivery IDs	DIY queue	✓
Action-contract registry (AI can't invent calls)	—	✓
Confirmation policy before side-effects	—	✓
100% audit-log coverage on actions	Manual logging	✓
Official PHP / Node / Python SDKs	Write your own	✓
OpenAPI 3.0.3 machine-readable contract	Maybe	✓
Sandbox keys + webhook tester	Build a staging rig	✓
Cloud & self-hosted parity (same code path)	Varie	✓
Connector pattern: platform code stays isolated	—	✓

FAQ

Questions des développeurs, répondu.

Auth, signatures, SDK, sandboxing et le modèle de connecteur : tout ce que vous demanderez avant la première demande.

Les appels API s'authentifient avec une seule clé Bearer à portée limitée : envoyez Authorization: Bearer opq_…. OpsIQ vérifie la portée de la clé et le rôle de l'acteur avant que quoi que ce soit ne s'exécute. Les webhooks sont séparés : chaque webhook envoyé par OpsIQ porte un X-OpsIQ-Signature (un HMAC-SHA256 hexadécimal du corps brut) et un X-OpsIQ-Timestamp pour la protection contre la répétition, afin que vous puissiez nous vérifier en retour, et les webhooks entrants que vous envoyez sont vérifiés de la même manière.

Non. L'IA ne peut proposer que des actions qui existent dans votre registre de contrats d'action. Elle ne peut pas inventer un appel. Chaque contrat déclare les surfaces, rôles et paramètres autorisés, et toute action marquée requires_confirmation affiche une carte d'aperçu à un humain avant que l'effet secondaire ne s'exécute.

Recalculer hash_hmac('sha256', $rawBody, $secret) (un hachage hexadécimal sans préfixe) et le comparer au X-OpsIQ-Signature en-tête avec un contrôle en temps constant (hash_equals). Chaque livraison porte également un horodatage, une clé d'idempotence et un ID de livraison que vous pouvez tracer. L'extrait PHP sur cette page est la vérification complète.

Les livraisons qui ne retournent pas un 200 sont réessayées avec un retour exponentiel, chacune portant la même clé d'idempotence afin qu'une livraison réessayée n'agisse jamais deux fois. Vous pouvez tracer chaque tentative par ID de livraison dans l'administration ou vos journaux.

SDK officiels pour PHP 8.4+, Node.js 18+ et Python 3.10+ gèrent la signature, les réessais, les clés d'idempotence et les réponses typées. Ce sont des wrappers légers autour de la surface REST, vous pouvez donc également générer votre propre client à partir du contrat OpenAPI 3.0.3 publié ou appeler l'API directement.

Oui. Chaque espace de travail expose un bac à sable avec sa propre clé à portée limitée qui touche la même surface API sans toucher aux données de production, plus POST /v1/webhooks/test pour envoyer une livraison d'échantillon signée à votre point de terminaison et confirmer votre vérification avant de passer en direct.

Oui. Les installations auto-hébergées exécutent le même chemin de code (la même signature, le même registre de connecteurs, le même contrat OpenAPI) donc il n'y a pas de dérive comportementale entre le cloud et sur site.

Un connecteur est un dossier autonome avec une classe PHP étendant AbstractConnector, plus actions.json et settings.json se manifeste. Vous mettez en œuvre identityProviders(), contextProviders(), registerActions(), subscribers() et handleWebhook(). OpsIQ le découvre automatiquement, relie les événements et garde votre code spécifique à la plateforme proprement séparé du noyau.