Cette page n’est pas encore disponible en Français ; elle s’affiche donc en anglais.
Integrations: the signed install handshake
app.json declares scopes, events and HTTPS URLs. At install your installUrl receives a scoped API key and a webhook secret, signed with your app secret.
{
"format": "zmle.app/1",
"name": "Hello Sync",
"version": "1.0.0",
"scopes": ["customers:read", "invoices:read"],
"events": ["invoice.sent", "invoice.paid"],
"webhookUrl": "https://hello-sync.example/zmle/webhook",
"installUrl": "https://hello-sync.example/zmle/install",
"uninstallUrl": "https://hello-sync.example/zmle/uninstall",
"configUrl": "https://hello-sync.example/settings",
"dataUse": "Reads customers and invoices to copy them into the Hello Sync bookkeeping service; …"
}scopes: API v1 scopes, no*.events: from the catalogue of 64, one by one — no wildcards; they need awebhookUrl.- URLs: public
https://only — no user / password, port, IP address,localhost,.local,.internalor.lan.installUrlis required when you ask for scopes. dataUse: 20–1,000 characters on what you read, why and where it goes; shown to buyers and reviewers.
POST /zmle/install
content-type: application/json
x-zmle-timestamp: 1792569600
x-zmle-signature: sha256=<hex of HMAC-SHA256(appSecret, "<timestamp>.<raw body>")>
{ "event": "app.installed", "listing": "hello-sync", "version": "1.0.0",
"workspace": { "id": "…", "slug": "acme", "url": "https://acme.<platform domain>" },
"api": { "base": "https://acme.<platform domain>/api/v1", "key": "fx_live_…", "scopes": ["customers:read", "invoices:read"] },
"webhook": { "secret": "whsec_…", "events": ["invoice.sent", "invoice.paid"] } }Verify the signature with your app secret (
mksec_…, in the portal after the first approval, rotatable) in constant time; reject timestamps older than 5 minutes (seereceiver.mjs).Answer 2xx within 10 seconds. Anything else cancels the install: the key is revoked, the endpoint removed and the owner sees the error.
Store the key encrypted — it is shown nowhere else. Webhooks then arrive at
webhookUrl, signed with thewhsec_…secret.Uninstall: after the key is revoked,
uninstallUrlgets{ "event": "app.uninstalled", listing, workspace, reason }, signed the same way. Delete data you no longer need.
.example, .test, .invalid or .localhost are simulated: the call is logged and recorded as simulated, never sent. Handy while developing; live listings use real hosts. configUrl opens in a new tab, never embedded.Written from: docs/DEVELOPERS/INTEGRATION-SPEC.md, examples/marketplace/integration-hello-sync/app.json, examples/marketplace/integration-hello-sync/receiver.mjs, src/lib/marketplace/install.ts, src/lib/marketplace/packages.ts, src/lib/integrations/events.ts