> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowapt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Webhooks

> Receive a POST from FlowIQ whenever a subscription is created, renewed, paused, resumed, changed or cancelled, or a payment fails.

Register a URL with [Create Webhook](https://docs.flowapt.com/flowiq-api-reference/endpoint/create-webhook.md) using `"platform": "subscriptions"`. FlowIQ then POSTs every matching subscription event to it, with the subscription as it is after the change.

```bash theme={null}
curl -X POST "https://api.flowiq.live/set-webhooks" \
  -H "Authorization: Bearer fiq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-system.example.com/flowiq/subscriptions",
    "platform": "subscriptions",
    "type": "all",
    "secret": "a-long-random-string"
  }'
```

Register one webhook per event with `type` set to the event name, or one with `"type": "all"` for every event. The same authentication options as messaging webhooks apply (`auth_type`: bearer, basic, api\_key, oauth2\_client\_credentials), and with a `secret` every request carries an `X-Flowiq-Signature: sha256=<hex>` HMAC of the raw body.

## Events

| `event_type` | When |
| - | - |
| `subscription.created` | A new subscription, with its first order placed |
| `subscription.renewed` | A later delivery was charged and its Shopify order created |
| `subscription.paused` | The subscription was paused |
| `subscription.resumed` | A paused subscription was resumed |
| `subscription.cancelled` | The subscription was cancelled |
| `subscription.reactivated` | A cancelled subscription was reactivated |
| `subscription.activated` | A migrated subscription was activated when the customer saved their card |
| `subscription.card_connected` | A customer saved their card on a subscription that stays paused |
| `subscription.items_changed` | Products added, removed or swapped. `data.scope` is `recurring` (every future delivery) or `one_order` (the next delivery only) |
| `subscription.updated` | Any other change. `data.change` names it: `skip_order`, `unskip_order`, `reschedule_order`, `retry_order`, `change_frequency`, `set_schedule`, `update_address`, `update_entry_address`, `update_amount`, `apply_credit`, `update_pause`, `set_discount_ladder`, `merge_subscriptions` |
| `subscription.expired` | The subscription expired |
| `payment.failed` | A delivery could not be charged |

## Payload

```json theme={null}
{
  "event_type": "subscription.renewed",
  "event_id": "1b9c7f0e-4d2a-4f3b-9a6e-2c8d7e5f1a90",
  "occurred_at": "2026-12-07T08:00:31.512Z",
  "organization_id": "a4234f32-…",
  "subscription_id": "3f2c6a1e-8b0d-4c55-9f7e-1d2a3b4c5d6e",
  "test": false,
  "source": "stitch",
  "data": {
    "order_number": 2,
    "shopify_order_id": 6098765432101,
    "shopify_order_name": "#35921",
    "amount_cents": 178400
  },
  "subscription": {
    "id": "3f2c6a1e-8b0d-4c55-9f7e-1d2a3b4c5d6e",
    "status": "active",
    "next_delivery": { "delivery_number": 3, "date": "2027-01-18", "scheduled_for": "2027-01-18T08:00:02+00:00", "estimated_total": "1701.50" }
  }
}
```

| Field | Notes |
| - | - |
| `event_id` | Unique per event (also in the `X-Flowiq-Event-Id` header). Use it to ignore a repeat |
| `test` | `true` when the event is about a [test subscription](https://docs.flowapt.com/flowiq-api-reference/subscriptions.md#test-subscriptions) |
| `data` | What changed; its fields depend on the event |
| `subscription` | The full [subscription object](https://docs.flowapt.com/flowiq-api-reference/subscriptions.md#the-subscription-object) after the change |

Headers: `X-Flowiq-Event` (the event type), `X-Flowiq-Event-Id`, `X-Flowiq-Signature` (when a secret is set).

> [!NOTE]
>
> Each event is sent once, with a 10-second timeout. Answer with a `2xx` quickly and do the work afterwards. If your endpoint was down, catch up with [List Subscriptions](https://docs.flowapt.com/flowiq-api-reference/endpoint/list-subscriptions.md) using `updated_since`, or read the [upcoming deliveries](https://docs.flowapt.com/flowiq-api-reference/endpoint/upcoming-deliveries.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.