Webhooks on Zid: subscribe, monitor health and recover broken endpoints

Why webhooks

Webhooks let Zid notify your app the moment something happens in a store, such as a new order, a product update or a customer login. You don't have to keep asking the API. That matters because Zid allows 60 requests per minute per application per store and explicitly asks partners not to poll for order or payment status.

There are two families of events:

• Store events (orders, products, carts, customers, categories). You subscribe per store through the Merchant API.
• App subscription events such as app.market.application.install, app.market.subscription.active and app.market.application.uninstall. You set these up in the Webhooks section of your app in the Partner Dashboard, with a target URL and optional extra headers.

The store events you can subscribe to

• Orders: order.create, order.status.update, order.payment_status.update
• Products: product.create, product.update, product.publish, product.delete
• Abandoned carts: abandoned_cart.created, abandoned_cart.completed
• Customers: customer.create, customer.update, customer.merchant.update, customer.login
• Categories: category.create, category.update, category.delete

order.create and order.status.update also accept conditions, so you only receive the events you care about. The supported keys are delivery_option_id, status and payment_method:

{
  "conditions": {
    "delivery_option_id": "55",
    "payment_method": "Cash On Delivery"
  }
}

Need an event or condition that doesn't exist yet? Zid invites suggestions through App Market support.

Create, list and delete subscriptions

All webhook endpoints need the Authorization and X-Manager-Token headers. Creating or deleting needs the third_webhook_write scope, and listing needs third_webhook_read.

POST   /v1/managers/webhooks
GET    /v1/managers/webhooks
DELETE /v1/managers/webhooks?original_id=2404

• Create requires event, target_url and original_id. conditions, username and password are optional.
• List returns the webhooks your app is subscribed to for that store.
• Delete removes a webhook by its original_id. The older delete-by-subscriber endpoint is marked deprecated.

If you set username and password, Zid sends every delivery with an Authorization: Basic header built from username:password in Base64. Check it on your side to confirm the request really came from Zid.

How health tracking works

Zid watches every endpoint with a circuit breaker, and each webhook has a health_status:

• healthy: deliveries go through as usual.
• degraded: 10 or more failures in the past hour. Zid still attempts delivery, but you should investigate.
• broken: 30 or more failures in the past hour. Delivery is suspended until you recover the webhook.

Failures are counted in a sliding one-hour window. A non-2xx response, a timeout or a similar error counts as a failure, and one successful delivery resets the count to healthy. A 429 response is not counted, because it tells Zid your endpoint is alive but rate-limited.

Before recording a failure, Zid retries a delivery up to 3 times, waiting 1, 5 and then 15 minutes. Only when all retries fail does the failure count toward the thresholds.

Broken webhooks and recovery

Once a webhook is broken, Zid dispatches no new events to it and discards pending undelivered events. You'll get an hourly batch email titled "Action Required: Your webhook endpoints are failing" with a broken_webhooks.csv attachment listing each broken webhook, its store, event, target URL and failure timestamps.

A broken webhook stays broken until you recover it through the API. Use GET /v1/managers/webhooks/health-summary for a quick count per state, and GET /v1/managers/webhooks/broken for the full list. Then recover:

POST /v1/managers/webhooks/broken/recover

{
  "webhooks": [
    {
      "broken_webhook_id": "{{webhook_uuid}}",
      "target_url": "https://your-new-endpoint.example.com/hook"
    }
  ]
}

• You must supply a new target_url. Reusing the old one is rejected, because Zid wants proof you've fixed the underlying problem.
• Zid soft-deletes the broken webhook, creates a new one for the same event, and starts it with a clean failure count.
• Partial failures are supported, so one bad item doesn't block the rest of the batch.

Good practices for your endpoint

• Use HTTPS with modern TLS. The Partner Dashboard validates URLs and expects TLS 1.2 or 1.3, a valid certificate, a publicly reachable server and a TLS handshake that completes within 5 seconds.
• Acknowledge fast. Return a 2xx quickly and do heavy work in the background, so slow processing doesn't turn into counted failures.
• Expect repeats. Retries mean the same event may reach you more than once. Make your handler safe to run twice.
• Rate-limit with 429. If you're overwhelmed, a 429 won't push you toward broken.
• Watch your health. Poll the health summary, read the failure emails, and check Webhook Logs in the Partner Dashboard, where you can view and retry deliveries.
• Test on a development store. Trigger real actions and confirm every subscribed event arrives before you submit.