Marketplace connectors

The marketplace is the in-product, installable side of the integrations ecosystem. Where the framework integrations are things you import into your code, a marketplace connector is something you install into a project so Zumik delivers events to a destination you own.

The first connector class is event destinations. Install one and Zumik delivers account events - today, budget-threshold alerts at 50/80/100% of a project's monthly budget - to Slack, Discord, or any HTTPS endpoint.

The catalog

curl https://api.zumik.ai/v2/marketplace/listings \
  -H "Authorization: Bearer $ZUMIK_API_KEY"

Install a connector

Installing is an admin action (it configures an outbound integration for the whole project). Provide the listing slug, an optional label, and the destination URL:

curl https://api.zumik.ai/v2/marketplace/installations \
  -H "Authorization: Bearer $ZUMIK_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "listing_slug": "slack",
    "name": "ops channel",
    "url": "https://hooks.slack.com/services/T0/B0/XXXX"
  }'

The URL is sealed at rest (AES-256-GCM, the same envelope as a BYOK key). The response - and every later read - returns only the destination host and a fingerprint, never the URL with its secret token:

{
  "id": "mki_...",
  "object": "marketplace_installation",
  "listing_slug": "slack",
  "name": "ops channel",
  "status": "active",
  "destination_host": "hooks.slack.com",
  "secret_fingerprint": "mkfp_8f1c2d3e4a5b",
  "last_delivery_status": null
}

You can do this from the console Marketplace tab too - it lists the catalog, installs, and manages connectors without the API.

Test it

Send a synthetic event and get the delivery result back inline, so you can confirm the connector works end to end:

curl -X POST https://api.zumik.ai/v2/marketplace/installations/mki_.../test \
  -H "Authorization: Bearer $ZUMIK_ADMIN_KEY"

{ "ok": true, "status": "delivered_200" }

Manage

Disabling stops delivery without losing the configuration; uninstalling drops the record and the sealed URL. Each installation also records its last_delivery_status and last_delivery_at so you can see whether the most recent event got through.

Delivery payloads

Each connector receives the shape its destination expects:

• Slack - { "text": "..." }

• Discord - { "content": "...", "allowed_mentions": { "parse": [] } }

• Custom webhook - a stable JSON envelope:

  {
    "source": "zumik",
    "type": "billing.budget.alert",
    "title": "Budget alert: 80% of monthly budget",
    "body": "Project ... crossed 80% of its monthly budget (cycle spend $...).",
    "data": { "project_id": "prj_...", "threshold_pct": 80, "cycle_spend_usd": 41.2 }
  }

Delivery is best-effort and fire-and-forget: a slow or failing destination never blocks or fails the request that produced the event.

Security

The destination URL is a customer-supplied SSRF surface, so install-time validation:

• requires https;
• pins the host for the managed connectors (hooks.slack.com for Slack, discord.com and friends for Discord);
• for the custom webhook, blocks loopback, private (RFC 1918), link-local / cloud-metadata (169.254.0.0/16), CGNAT, and IPv6 ULA / link-local destinations, plus obvious internal names (localhost, *.local, *.internal).

This is a boundary check, not a substitute for network egress filtering - a hardened deployment should also egress-filter the delivery path against DNS rebinding. The URL is never logged; delivery errors are recorded coarsely (timeout, connect_error, http_500) so a transport error can't leak the resolved address.