# Webhook subscriptions

> A Webhook subscription sends an HTTPS request to your endpoint whenever a topic fires.
{/* generated:versioned-pages - edit _pm-authored, not this file */}

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](/api/product-management/webhook-topics/) (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

## 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

### Version

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

```
Flowkiwi-Api-Version: unstable
```

### 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

`PATCH` uses [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7396) with `Content-Type: application/merge-patch+json`.