Webhooks

Get an HTTPS POST the moment something happens in your school — a sale, an enrollment, a completed lesson — instead of polling the API.

Register an endpoint

1. Sign in at app.zinstruct.com as an owner or admin and open Settings → Webhooks.
2. Click Open webhook portal. The portal is where you add an endpoint URL, choose which events it receives, copy its signing secret, browse delivery logs and replay a failed delivery.
3. Give each receiving system its own endpoint, so each gets its own secret and its own log.

The payload

Every event arrives as a JSON POST in the same envelope. api_version is currently 2026-05-24.

{
  "id": "0b6f3a52-6a4e-4d0e-9a4c-2f1f8f0d6a11",
  "type": "enrollment.created",
  "api_version": "2026-05-24",
  "created_at": "2026-01-15T09:30:00.000Z",
  "data": {
    "tenant_id": "8a1c2e34-5b6d-4f70-8a9b-0c1d2e3f4a5b",
    "enrollment_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
    "product_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a",
    "contact_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",
    "enrolled_at": "2026-01-15T09:30:00.000Z"
  }
}

Verify the signature

Deliveries are signed by Svix, which runs our webhook delivery. Each request carries three headers: svix-id, svix-timestamp and svix-signature. Check them against the endpoint's signing secret (it starts with whsec_) before trusting the body. The simplest way is Svix's open-source library, available for most languages:

import { Webhook } from 'svix' // npm install svix

const wh = new Webhook(process.env.WEBHOOK_SECRET) // whsec_… from the webhook portal

// Verify the RAW request body — re-serialised JSON will not match the signature.
export function handle(rawBody, headers) {
  const event = wh.verify(rawBody, {
    'svix-id': headers['svix-id'],
    'svix-timestamp': headers['svix-timestamp'],
    'svix-signature': headers['svix-signature'],
  }) // throws if the signature or timestamp is wrong
  return event // { id, type, api_version, created_at, data }
}

Or verify by hand — an HMAC-SHA256 over {svix-id}.{svix-timestamp}.{raw body}:

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verify(rawBody, headers, secret) {
  const id = headers['svix-id']
  const timestamp = headers['svix-timestamp']
  // Reject stale deliveries (here: older or newer than 5 minutes).
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest()
  // The header can hold several space-separated signatures: "v1,<base64> v1,<base64>"
  return headers['svix-signature'].split(' ').some((part) => {
    const [version, sig] = part.split(',')
    const given = Buffer.from(sig ?? '', 'base64')
    return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected)
  })
}

Svix documents the scheme in full, with libraries for other languages, in Verifying webhooks.

Delivery

• Answer with any 2xx status to acknowledge a delivery.
• A failed delivery is retried automatically. Every attempt is in the portal's delivery log, and you can replay a delivery from there.
• Delivery is at least once: the same event can arrive more than once. Its id never changes between attempts, so record the ids you have handled and skip repeats.
• Events can arrive out of order. Use created_at when order matters.

Events

100 event types. Each lists the fields of data. solid fields are always present; dashed fields are sent only by some of the actions that raise the event.