Webflow — Ranket Docs

Ranket connects to a CMS Collection on your Webflow site and publishes generated articles as collection items. Each article ships with title, slug, HTML body, excerpt, meta title/description, and a hero image URL — mapped onto your collection’s field slugs. Updates and deletes propagate to the same item.

Setup with one click (recommended)

In your brand settings → Webhooks, click Add destination → Webflow → Connect with Webflow.
Webflow opens a permission screen. Authorize the Ranket app for the workspace and site you want articles published to.
After authorization, pick the site and the CMS collection that holds your articles.
Done — Ranket now publishes new articles to that collection automatically.

The OAuth token does not auto-expire. If you ever revoke Ranket’s access from your Webflow account settings, just re-run the connect flow to mint a new token.

Setup with an API token (alternative)

Use this path when you can’t (or don’t want to) authorize the Ranket OAuth app — for example if your workspace policy prefers scoped Site API tokens.

What you need before you start

A Webflow site on a paid Site Plan (the free Starter plan does not include CMS API write access).
A Workspace role of Admin or Editor with permission to generate site API tokens (Workspace settings → Members → role permissions).
A CMS Collection on the site that will hold your articles. Most users target a Blog Posts collection — but any collection will work as long as it has fields for title, slug, and body.
The field slugs of your collection. Webflow auto-generates slugs from field names (e.g. a field called “Meta Title” becomes meta-title). You’ll need them to map our payload.

Step-by-step setup

In Webflow, open the target site and go to Site settings → Apps & Integrations → API access.
Click Generate API token. Name it Ranket and select scopes: at minimum CMS: Read and write and Sites: Read. Click Generate.
Copy the token (a long opaque string). Webflow shows it once — store it safely.
Find your Site ID and Collection ID:
- Site ID — open Site settings → General and copy the Site ID, or call GET https://api.webflow.com/v2/sites with your token.
- Collection ID — in the Designer, open the collection’s settings; the ID is in the URL, or call GET https://api.webflow.com/v2/sites/<siteId>/collections.
Note the field slugs for the collection fields you want to map. Open the collection in the Webflow Designer, click each field, and copy the slug shown under the field name.
In Ranket, open your brand → Webhooks tab → Add endpoint and pick Webflow.
Paste the API Token, Site ID, and Collection ID.
Fill in the Field Mapping — map each Ranket field to the matching slug in your collection. Defaults (name, slug, body, excerpt, meta-title, meta-description, main-image) match a freshly cloned Webflow blog template; adjust if yours differs.
Toggle Publish Live if you want items to go live immediately; leave off to land them as staged drafts.
Click Test connection before saving — Ranket hits /v2/collections/<collectionId> to confirm the token, site, and collection all line up.

Configuration options

Field	Required	Default	What it does
`siteId`	yes	—	Site ID. Used for scoping the publish step.
`collectionId`	yes	—	Collection ID where articles are created as items.
`apiToken`	yes	—	Site API token with `CMS:write` and `Sites:read` scopes.
`fieldMapping.title`	yes	`name`	Slug of the collection field that stores the article title.
`fieldMapping.slug`	yes	`slug`	Slug field (Webflow’s built-in slug field is always `slug`).
`fieldMapping.body`	yes	`body`	Rich-text field that stores the HTML body.
`fieldMapping.excerpt`	no	`excerpt`	Plain-text field for the excerpt. Omit to skip.
`fieldMapping.metaTitle`	no	`meta-title`	Field for the SEO meta title.
`fieldMapping.metaDescription`	no	`meta-description`	Field for the SEO meta description.
`fieldMapping.mainImage`	no	`main-image`	Image field for the hero image. We send `{ url }`; Webflow ingests the asset.
`publishLive`	no	`true`	When `true`, runs the v2 publish step after creating the item so it goes live on the production site.

What gets sent

Each article.published event creates an item via POST /v2/collections/<collectionId>/items with:

fieldData populated from your mapping (title, slug, body, excerpt, meta title, meta description, main image).
isDraft: false and isArchived: false when publishLive is on; isDraft: true otherwise.

When publishLive is on, a follow-up POST /v2/collections/<collectionId>/items/publish pushes the item to the live site. Image fields receive a { url: ... } object — Webflow downloads and rehosts the asset on its CDN.

JSON-LD schema and FAQ blocks are present in the original webhook payload but are not auto-mapped; if you want them on-page, render them from a custom code embed in your collection template.

Updates and deletes

When Ranket optimizes an article, the same endpoint receives an article.updated event and the item is updated in place via PATCH /v2/collections/<collectionId>/items/<id>. Deletions fire article.deleted and the item is removed via DELETE.

Troubleshooting

401 Unauthorized — token is wrong, expired, or was revoked. Generate a new one in Site settings.
403 Forbidden — the token lacks CMS:write. Generate a new token with the correct scopes (Webflow doesn’t let you add scopes to an existing token).
400 “Validation Error” on field slugs — one of the slugs in your fieldMapping doesn’t exist on the collection, or you mapped a non-rich-text field to body. Re-check each slug in the Designer.
400 on the slug field — the slug already exists on another item in the collection. Webflow enforces unique slugs per collection; let Ranket regenerate the slug or delete the older item first.
publishLive step fails silently — Ranket logs a warning but the item still exists as a draft. Most often caused by site rate limits (Webflow throttles publish calls heavily). You can publish from the Designer manually or wait and the next run will succeed.