Skip to content
Flowkiwi Flowkiwi Docs

Webhook subscriptions

View as Markdown

A Webhook subscription tells Flowkiwi to call your endpoint when something happens in your catalog, instead of you polling for changes. It pairs a webhook topic (such as product/updated) with the HTTPS callbackUrl to notify.

Each subscription pins the API version of the payload it receives (such as 2026-07), so the shape delivered to you never changes without you asking. Use includeFields to receive only part of the payload: a list of dot-path fields, where a * segment is a wildcard (*.id). The resource id is always included, and an empty list means the full payload.

The Webhook subscription object

Section titled “The Webhook subscription object”

No properties.

Common workflows

Section titled “Common workflows”
  • Get notified of product changes. Create a subscription for product/created, product/updated or product/deleted, with the callbackUrl of your endpoint.
  • Verify deliveries. Store the signing secret returned by the creation response - it is returned only once.
  • Trim the payload. Set includeFields to the fields your integration actually reads.

Conventions

Section titled “Conventions”

Version

Section titled “Version”

This resource is only available in the unstable version. Select it with the request header:

Flowkiwi-Api-Version: unstable

Authentication and headers

Section titled “Authentication and headers”

All requests require an OAuth 2.0 bearer token:

Authorization: Bearer <token>

Reading requires the webhooks:read scope; writing also requires webhooks:write.

Partial updates

Section titled “Partial updates”

PATCH uses JSON Merge Patch with Content-Type: application/merge-patch+json.