Build and Publish a Fluid Droplet: Setup to Marketplace

Droplets are third-party integrations that merchants install directly from the Fluid Marketplace. When a merchant installs your Droplet, Fluid sends a signed webhook to your server, and you exchange a short-lived token for long-lived credentials scoped to that merchant’s account. This guide walks through building, testing, and submitting a Droplet from start to finish.

This guide manages your Droplet with the v2026-10 company droplets API: Create a droplet for your company, Update a droplet, and Rotate a droplet’s webhook secret. The credential exchange uses Exchange an install token for installation credentials. The unversioned /api/droplets endpoints will soon be deprecated, so use the v2026-10 endpoints for new work.

Create the Droplet via API

Register your Droplet with Fluid by sending a POST request to /api/company/v2026-10/droplets. The payload defines your Droplet’s title, the URL Fluid will load in the merchant dashboard, the webhook endpoints Fluid calls during installation and uninstallation, and its Marketplace listing.

curl -X POST https://api.fluid.app/api/company/v2026-10/droplets \
  -H "Authorization: Bearer <your_company_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "droplet": {
      "title": "Harborline Loyalty",
      "embed_url": "https://app.harborline.example/droplet",
      "install_webhook_url": "https://app.harborline.example/webhooks/install",
      "uninstall_webhook_url": "https://app.harborline.example/webhooks/uninstall",
      "summary": "Reward repeat customers with points they can spend at checkout.",
      "description": "<p>Harborline Loyalty gives every customer a points balance that grows with each order.</p>"
    }
  }'

Fluid creates the Droplet as a draft and returns it under a droplet key. Save droplet.uuid; you’ll need it to manage the Droplet later.The create response doesn’t include the Droplet’s webhook secret. Get it by rotating the secret once with POST /api/company/v2026-10/droplets/{uuid}/webhook-secret-rotations, and store it as WEBHOOK_SECRET on your server. The response shows the new secret only once. Each later rotation replaces the secret immediately, so update your server straight away.

Implement the Install Webhook Handler

When a merchant installs your Droplet, Fluid sends a signed POST request to your install_webhook_url. Your handler must verify the signature and then exchange the included exchange_token for long-lived credentials.

const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.raw({ type: 'application/json' }));

app.post('/webhooks/install', async (req, res) => {
  const timestamp = req.headers['x-fluid-timestamp'];
  const signature = req.headers['x-fluid-signature'];
  const shop = req.headers['x-fluid-shop'];
  const rawBody = req.body.toString();

  // Verify the signature before proceeding
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }

  // Reject requests older than 5 minutes
  const age = Date.now() / 1000 - parseInt(timestamp, 10);
  if (age > 300) {
    return res.status(401).send('Request expired');
  }

  const { exchange_token } = JSON.parse(rawBody);

  // Exchange the token for credentials
  const credResponse = await fetch(
    'https://api.fluid.app/api/droplet_installations/exchange',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ exchange_token })
    }
  );

  const credentials = await credResponse.json();
  // Store credentials securely — see Step 4
  await saveCredentials(shop, credentials);

  res.sendStatus(200);
});

Exchange the Token for Credentials

The exchange_token included in the install webhook is single-use and expires after 10 minutes. Exchange it immediately for long-lived credentials:

The request needs no Authorization header — the exchange token is the credential.

curl -X POST https://api.fluid.app/api/droplet_installations/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_token": "<exchange_token_from_webhook>"
  }'

The response contains two tokens you must store securely:

{
  "droplet_installation": {
    "droplet_installation_uuid": "dri_4Kq9ZtVb2mXw7RcN8pLs3JdH",
    "droplet_uuid": "drp_7Hn2WqLx9cVt4BzK6mRp8YsD",
    "fluid_company_id": 1482,
    "fluid_shop": "harborline.fluid.app"
  },
  "credentials": {
    "authentication_token": "dit_9XcT3vMq7LpW2nRb5KsZ8hJf",
    "webhook_verification_token": "wvt_2BfR8kNs5QmY7tLx3VpC9gWd",
    "issued_at": "2026-09-28T17:42:11Z",
    "token_type": "bearer"
  }
}

Field	Prefix	Purpose
`credentials.authentication_token`	`dit_`	Your droplet installation token. Use it as a Bearer token in API calls for this company.
`credentials.webhook_verification_token`	`wvt_`	Verify incoming webhooks from this company’s installation
`droplet_installation.droplet_installation_uuid`	`dri_`	Identifies this installation. Store it with the credentials.

Store Credentials and Register Webhooks

Store the authentication_token and webhook_verification_token in your database, keyed by shop domain or installation ID. These credentials represent one merchant’s installation — each merchant who installs your Droplet gets their own set.After storing credentials, optionally register webhooks or drop zones for the merchant with the published POST /api/company/webhooks endpoint — see the Register and handle webhooks guide for the full registration, delivery, and verification contract:

async function saveCredentials(exchange) {
  const { droplet_installation: installation, credentials } = exchange;

  await db.installations.upsert({
    shop: installation.fluid_shop,
    installation_id: installation.droplet_installation_uuid,
    authentication_token: credentials.authentication_token,
    webhook_verification_token: credentials.webhook_verification_token
  });

  // Register webhooks for this merchant
  await fetch('https://api.fluid.app/api/company/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${credentials.authentication_token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      webhook: {
        resource: 'order',
        event: 'created',
        url: 'https://app.example.com/webhooks/orders',
        active: true,
        http_method: 'post'
      }
    })
  });
}

Implement the Uninstall Handler

When a merchant uninstalls your Droplet, Fluid sends a signed webhook to your uninstall_webhook_url. Verify the signature the same way as the install handler, then clean up the merchant’s credentials and any associated resources.

app.post('/webhooks/uninstall', (req, res) => {
  const timestamp = req.headers['x-fluid-timestamp'];
  const signature = req.headers['x-fluid-signature'];
  const shop = req.headers['x-fluid-shop'];
  const rawBody = req.body.toString();

  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }

  const age = Date.now() / 1000 - parseInt(timestamp, 10);
  if (age > 300) {
    return res.status(401).send('Request expired');
  }

  // Remove stored credentials for this merchant
  db.installations.delete({ shop });

  res.sendStatus(200);
});

Test Locally with ngrok

Fluid must be able to reach your webhook endpoints over HTTPS. During development, use ngrok to expose your local server:

ngrok http 3000

ngrok prints a public HTTPS URL such as https://a1b2c3d4.ngrok.io. Update your Droplet’s install_webhook_url and uninstall_webhook_url to use this URL while testing:

curl -X PATCH https://api.fluid.app/api/company/v2026-10/droplets/<droplet_uuid> \
  -H "Authorization: Bearer <your_company_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "droplet": {
      "install_webhook_url": "https://a1b2c3d4.ngrok.io/webhooks/install",
      "uninstall_webhook_url": "https://a1b2c3d4.ngrok.io/webhooks/uninstall"
    }
  }'

Remember to swap back to your production URLs before submitting for Marketplace approval.

Submit for Marketplace Approval

Once your Droplet is working end-to-end, contact Fluid to begin the Marketplace review process. Fluid will review your Droplet’s functionality, security, and listing content before making it available to merchants.

Your Droplet will not appear in the Fluid Marketplace until it has been reviewed and approved by Fluid. Complete its listing (summary, description, logo_url, and features) before submitting.

Verifying Webhook Signatures

Every webhook Fluid sends is signed with HMAC-SHA256. Verify the signature on every incoming request to ensure it genuinely came from Fluid. Reject any request where the timestamp is more than 5 minutes old to prevent replay attacks. This is the same signing scheme documented in the Register and handle webhooks guide — Fluid computes the HMAC over <timestamp>.<raw_body> using your shared secret. Fluid includes three headers on every webhook:

Header	Description
`X-Fluid-Shop`	The shop domain of the merchant
`X-Fluid-Timestamp`	Unix timestamp when the request was sent
`X-Fluid-Signature`	HMAC-SHA256 of `"#{timestamp}.#{raw_body}"` using your webhook secret

Node.js

const crypto = require('crypto');

function verifySignature(rawBody, timestamp, signature, secret) {
  const age = Date.now() / 1000 - parseInt(timestamp, 10);
  if (age > 300) throw new Error('Webhook timestamp too old');

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    throw new Error('Invalid webhook signature');
  }
}

Ruby

require 'openssl'

def verify_signature(raw_body, timestamp, signature, secret)
  age = Time.now.to_i - timestamp.to_i
  raise 'Webhook timestamp too old' if age > 300

  expected = OpenSSL::HMAC.hexdigest('SHA256', secret, "#{timestamp}.#{raw_body}")
  raise 'Invalid webhook signature' unless Rack::Utils.secure_compare(signature, expected)
end

Identifying Merchants in Your Embed

Fluid appends the Droplet installation UUID as a dri query parameter to your embed_url whenever it loads the Droplet inside the merchant’s dashboard. Use this value to look up the correct authentication_token for the current merchant:

https://app.example.com/droplet?dri=dri_xxxxxxxxxxxx

const params = new URLSearchParams(window.location.search);
const installationId = params.get('dri');

const credentials = await db.installations.findBy({ installation_id: installationId });
// Use credentials.authentication_token for API calls on behalf of this merchant

Token Scopes

Your authentication_token is limited by the scopes granted to your droplet’s installation. By default, those are the scopes your droplet requests. A request to an endpoint whose scope the installation lacks returns 403. The available scopes are:

Scope	Description
`main`	Core account data
`prospects`	Leads and prospect records
`members`	Member and customer data
`web`	Web presence and pages
`settings`	Account configuration
`products`	Product catalog
`orders`	Order management
`users`	Admin user accounts
`website`	Website builder resources
`header_menus`	Navigation menu configuration
`payments`	Payment settings and transactions
`tax_filings`	Tax filing reports

To find out why a request returns 403, see Debug a 403 from a Droplet token.

Check your Droplet works for every company

Before you ask Fluid to publish your Droplet, check that it works for many companies at once, not only yours. Each company that installs it gets its own installation and its own credentials.

No hard-coded companies. Don’t put a company ID, shop name or token in your code or configuration. Find the company from the installation on every request.
One set of credentials per installation. Store each installation’s authentication_token and webhook_verification_token against that installation, and look them up by the dri value or the webhook’s X-Fluid-Shop.
Scope everything by installation. Every database row, cache key, file and background job belongs to one installation. A query without that filter can show one company’s data to another.
Call Fluid with the installation’s token. Use the installation’s dit_ token, not your own API token or sign-in. Your token reaches only your company, and it keeps working after you leave.
Verify each company’s webhooks with its own secret. A secret shared across companies can’t tell their deliveries apart.
Clean up on uninstall. When droplet.uninstalled arrives, revoke and delete that installation’s credentials and stop its jobs.
Test with a second company. Install the Droplet in a second company too, and check that neither company sees the other’s data. A draft Droplet installs only in your own company. See Who can install your Droplet.

Droplets: what Droplets are and how they fit into Fluid.
Embed apps with drop zones
Get user information in mobile and Portal widgets

Get started

Mist apps

Core concepts

Guides

Guided setup

Storefront guides

SDKs

Portal & Widgets

Build and Publish a Fluid Droplet: Setup to Marketplace

Verifying Webhook Signatures

Identifying Merchants in Your Embed

Token Scopes

Check your Droplet works for every company

​Verifying Webhook Signatures

​Identifying Merchants in Your Embed

​Token Scopes

​Check your Droplet works for every company

​Related pages

Verifying Webhook Signatures

Identifying Merchants in Your Embed

Token Scopes

Check your Droplet works for every company

Related pages