Skip to content
zonoDocs
On this page

Webhooks

Issue tracker webhook setup

Where Linear, GitHub and the Zono Shopify app send events, which secret signs them, what Zono checks before it accepts a delivery, and what to look at when something does not arrive.

Providers call these URLs to deliver events to Zono. Each one checks a signature or shared secret before it reads the payload, answers 2xx quickly and does the work on a queue. A delivery Zono has already processed is acknowledged with 200 and ignored, so provider retries never create duplicates. These are inbound webhooks; the signed webhooks Zono sends to your own endpoints are documented in the REST API reference.

Outbound signed webhooks in the REST API reference

Linear issue sync

Linear sends issue updates to this URL, so the status of issues linked to tickets stays current within seconds. Every Linear integration has its own URL and secret.

Set up by: Team admins, under Workspace settings > Issue Trackers (Premium).

Webhook URL for one integration (shown on the Linear card)

POSThttps://zono.support/api/webhook/issues/linear/{integration_id}

Setup

  1. Connect Linear with a personal API key or OAuth under Workspace settings > Issue Trackers.
  2. With an admin API key, click Set up webhook: Zono creates a webhook for issues in all public teams with a fresh secret. Click Re-register webhook to rotate the secret.
  3. Linear only lets apps with admin access create webhooks, so an OAuth connection (or a key without admin access) adds it by hand: in Linear, Settings > API > Webhooks > New webhook, with the URL from the Linear card and the Issues data change event. Paste the signing secret Linear shows into "Linear signing secret" in Zono.
  4. Issues in private Linear teams are not sent to a webhook for all public teams; Zono refreshes linked issues every hour instead.

Headers

Linear-SignatureHex HMAC-SHA256 of the raw request body, keyed with the webhook's signing secret.
Linear-DeliveryThe delivery id, used to recognise a retried delivery.

What Zono verifies

  • The URL must name a Linear integration, or Zono answers 404.
  • The signature must match the integration's secret and the payload's webhookTimestamp must be within 60 seconds, or Zono answers 401.
  • A delivery id seen in the last 24 hours is acknowledged without work.
  • Only Issue events are applied; a remove action marks the linked issue as removed. Events for an inactive integration, or a workspace without Premium, are acknowledged and ignored.
  • Each URL accepts up to 120 deliveries a minute.

Troubleshooting

  • 401 "Invalid signature": the signing secret in Zono is not the one Linear shows for this webhook, or the server clock is off by more than a minute.
  • Nothing updates after Set up webhook: the API key has no admin access. Add the webhook by hand and paste its signing secret.
  • Issues in a private team never update instantly: expected, they are refreshed hourly.
  • The card shows the last webhook time; if it never changes, check the webhook in Linear is enabled and points at the URL on the card.

GitHub issue sync

GitHub sends issue events from your allowed repositories to this URL, so issues linked to tickets stay current within seconds. Every GitHub integration has its own URL and secret.

Set up by: Team admins, under Workspace settings > Issue Trackers (Premium).

Webhook URL for one integration (shown on the GitHub card)

POSThttps://zono.support/api/webhook/issues/github/{integration_id}

Setup

  1. Connect GitHub with a fine-grained personal access token with Issues (read and write) and Metadata (read), and list the repositories Zono may use.
  2. Add Webhooks (read and write) to the token and click Set up webhook: Zono creates a hook on each allowed repository (content type application/json, the Issues event) with a fresh secret. Click Re-register webhook to rotate it.
  3. Without that permission, Zono shows the URL and a new secret once. In each allowed repository open Settings > Webhooks > Add webhook, set content type application/json, choose "Let me select individual events" and tick Issues.

Headers

X-Hub-Signature-256"sha256=" followed by the hex HMAC-SHA256 of the raw request body, keyed with the integration's webhook secret.
X-GitHub-EventOnly issues events are applied; ping and every other event are acknowledged and ignored.
X-GitHub-DeliveryThe delivery id, used to recognise a redelivery.

What Zono verifies

  • The URL must name a GitHub integration, or Zono answers 404.
  • The signature must match the integration's webhook secret, or Zono answers 401.
  • A delivery id seen in the last 24 hours is acknowledged without work.
  • Pull requests are ignored; a deleted action marks the linked issue as removed. Events for an inactive integration, or a workspace without Premium, are acknowledged and ignored.
  • Each URL accepts up to 120 deliveries a minute.

Troubleshooting

  • Set up webhook fails with a permissions error: add Webhooks (read and write) to the token, or add the hook by hand.
  • 401 "Invalid signature": the hook was created with an older secret. Click Re-register webhook, or paste the secret Zono shows into the hook.
  • GitHub shows deliveries with 200 but nothing changes: the event is not issues, or the issue is a pull request.
  • Use Recent Deliveries on the hook in GitHub to redeliver an event after fixing the secret.

Shopify app (managed by Zono)

Zono's Shopify app receives Shopify's mandatory privacy webhooks and the uninstall event here. Nothing to configure: it is registered in Zono's own Shopify app.

Set up by: Zono. Merchants and teams never set this up.

Shopify app webhook URL

POSThttps://zono.support/api/webhook/shopify

Setup

  1. Topics handled: app/uninstalled marks the store connection inactive, customers/redact deletes that store's linked customers, shop/redact removes the connection, and customers/data_request is recorded for the team.

Headers

X-Shopify-Hmac-Sha256Base64 HMAC-SHA256 of the raw request body, keyed with Zono's Shopify app secret.
X-Shopify-TopicThe event topic.
X-Shopify-Shop-DomainThe store the event is about.

What Zono verifies

  • The HMAC must match Zono's app secret, or Zono answers 401. A payload seen before is refused as a replay.

Troubleshooting

  • A store that uninstalled the app shows its connection as inactive; connect it again in Zono after reinstalling.