Skip to main content
< All Topics
Print
Posted
Updated
Byadmin

The store must have webhooks enabled. Any registered developer may subscribe to any enabled store by handle (not only stores they own). You only see and manage your own subscriptions.

Create a subscription

POST /v1/developer/webhooks/{shop_handle}
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "name": "Order created",
  "url": "https://your-app.example.com/webhooks/zencommerce",
  "event": "order.create"
}

Response (201) — signing secret is returned once:

{
  "webhook": {
    "id": 42,
    "name": "Order created",
    "event": "order.create",
    "url": "https://your-app.example.com/webhooks/zencommerce",
    "is_active": true,
    "shop_id": 866,
    "developer_id": 1,
    "secret": "…",
    "created_at": "2026-10-06T12:05:00+00:00",
    "updated_at": null
  },
  "notice": "Store the webhook signing secret now — it is only returned on create or rotate."
}

Destination URLs must use HTTPS (http://localhost is allowed only in local development).

Endpoints

Action Method & path
List supported events GET /v1/developer/webhooks/events (public)
List my subscriptions for a shop GET /v1/developer/webhooks/{shop_handle}
Create POST /v1/developer/webhooks/{shop_handle}
Read one GET /v1/developer/webhooks/{shop_handle}/{id}
Update PUT /v1/developer/webhooks/{shop_handle}/{id}
Rotate signing secret POST /v1/developer/webhooks/{shop_handle}/{id}/rotate-secret
Delete DELETE /v1/developer/webhooks/{shop_handle}/{id}

Create body fields

Field Required Description
event yes One of the supported event names
url yes HTTPS endpoint that will receive POSTs
name no Human-readable label
secret no Optional custom signing secret (min 16 characters). If omitted, Zencommerce generates one
is_active no Defaults to true

Update body fields

Field Required Description
event no Change subscribed event
url no Change HTTPS destination
name no Change label (null / empty clears)
is_active no Enable or disable without deleting

Maintain a subscription

Disable

PUT /v1/developer/webhooks/{shop_handle}/{id}
Authorization: Bearer {access_token}
Content-Type: application/json

{ "is_active": false }

Rotate signing secret (new secret returned once — update your receiver immediately)

POST /v1/developer/webhooks/{shop_handle}/{id}/rotate-secret
Authorization: Bearer {access_token}

Delete

DELETE /v1/developer/webhooks/{shop_handle}/{id}
Authorization: Bearer {access_token}

Admin API for the merchant and staff master switch

Method Path Purpose
GET /v1/admin/settings/integrations/webhooks Read enabled status and counts
PUT /v1/admin/settings/integrations/webhooks Set { “enabled”: true | false }
GET /v1/admin/settings/integrations/webhooks/events List supported events
Scroll to Top

Powered by CookieAdmin