مواد پر جائیں
14 دن کا مفت ٹرائل، کارڈ کی ضرورت نہیں9 زبانیں176 کاروباری اقسام · 50 ایپس
UR· USD
لائیو ڈیمو آزمائیںمفت آزمائش شروع کریں

یہ صفحہ ابھی اردو میں دستیاب نہیں، اس لیے انگریزی میں دکھایا جا رہا ہے۔

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.

  • about 9 min
examples/marketplace/integration-hello-sync/app.json
{
  "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 a webhookUrl.
  • URLs: public https:// only — no user / password, port, IP address, localhost, .local, .internal or .lan. installUrl is 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.
The install call
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"] } }
  1. 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 (see receiver.mjs).

  2. Answer 2xx within 10 seconds. Anything else cancels the install: the key is revoked, the endpoint removed and the owner sees the error.

  3. Store the key encrypted — it is shown nowhere else. Webhooks then arrive at webhookUrl, signed with the whsec_… secret.

  4. Uninstall: after the key is revoked, uninstallUrl gets { "event": "app.uninstalled", listing, workspace, reason }, signed the same way. Delete data you no longer need.

Hosts ending in .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