Subscribing

Your app manages its own subscriptions through the API. It sees and changes only the subscriptions it created — never the merchant’s own, never another app’s.

Create — POST /apps/webhooks/subscriptions (write_webhooks)

{
  "url": "https://hooks.your-app.example/ciqra",
  "eventTypes": ["order.paid", "order.shipped"],
  "description": "Fulfilment sync"
}

Field	Rule
url	Absolute URL, at most 2048 characters, not a private address. Use https.
eventTypes	Required, non-empty. Each must be a known event (case-insensitive) that your installation’s scopes let it receive — order.* needs read_orders, and so on.
description	Optional, at most 256 characters.

You do not send a secret: deliveries are signed with your installation’s signing secret (ciqra_ss_…), which you received at installation. Response 200:

{
  "id": "…", "url": "https://hooks.your-app.example/ciqra", "description": "Fulfilment sync",
  "eventTypes": ["order.paid", "order.shipped"], "isActive": true, "hasSigningSecret": true,
  "isDeliverable": true, "createdAt": "…", "updatedAt": null, "installationId": "…"
}

Validation failures are 400 with {"error": "…"}. Asking for an event you cannot receive names the missing scope:

{ "error": "This installation cannot receive: order.paid (needs read_orders)." }

An empty eventTypes is refused: an app subscribes to named events only, so a new event type added to the platform never reaches an app the merchant did not grant it to.

List — GET /apps/webhooks/subscriptions (read_webhooks)

Returns this installation’s subscriptions as an array of the object above.

Remove — DELETE /apps/webhooks/subscriptions/{id} (write_webhooks)

204, or 404 if the subscription is not yours. Deliveries already queued for it are dropped.

There is no update route: to change a URL or event list, create the new subscription first, then delete the old one, so no event falls between them.

When the app is uninstalled

All of the installation’s subscriptions are deactivated and removed, and queued deliveries are dropped. Nothing is delivered after uninstall.