Webhooks & signature verification

Zentag delivers signed HTTP POST callbacks when domain events occur. Register
endpoints in Settings → Partner integrations → Webhooks, or with the
webhooks:manage scope via POST /webhook-endpoints.

Webhooks are the primary way to learn that asynchronous work finished. Every
endpoint that returns 202 hands you a job id, and the matching event carries
that id back in job_id.

Payload

{
  "id": "evt_1a2b3c",
  "type": "clip.ready",
  "created_at": "2026-07-01T18:24:00.000Z",
  "job_id": "job_autoflip_9f2c1d4e7a8b3c50",
  "idempotency_key": "my-retry-key-42",
  "data": {
    "object": "clip",
    "id": "clip_123",
    "status": "COMPLETED",
    "variants": [
      { "aspect_ratio": "9:16", "video_url": "https://...", "status": "completed" }
    ]
  }
}

Event reference

Clips

clip.ready is not once-per-clip. A clip that is created, then autoflipped
to 9:16, then cropped, emits three clip.ready events. Distinguish them by
job_id, and treat the event as "this clip changed, here is its current state"
rather than "this clip is now finished".

Highlights

POST /highlights/generate returns 202 immediately, and one of the two events
above follows when rendering finishes, which can be minutes later. Use
GET /highlights/{id}/progress to drive a progress bar in the meantime.

Publishing

Streams

Headers

Verifying the signature

The signature is HMAC-SHA256(signing_secret, "{timestamp}.{raw_body}").

Verify against the raw request body, before any JSON parsing. Parsing and
re-serializing changes the bytes and the signature will not match. Compare with
a constant-time function, and reject timestamps outside a ~5 minute window to
limit replay.

Your signing secret is returned once, in the response to
POST /webhook-endpoints. It is never retrievable afterwards; only the last
four characters are shown. If you lose it, delete the endpoint and create a new
one.

Node.js

import crypto from "node:crypto";

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python

import hashlib, hmac

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=") for p in header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Delivery guarantees

Read this section before writing your handler. The guarantees are weaker than
people usually assume.

At-least-once, not exactly-once. An event can arrive more than once. The
most common cause is your endpoint doing the work successfully but responding
too slowly, so Zentag records a timeout and retries.

Deduplicate on id. Keep a record of processed event ids and ignore
repeats. id is stable across retries and across manual replays; the
Zentag-Delivery header is not, so do not use it for this.

No ordering guarantee. Events are delivered independently and retries
reorder them. clip.ready can arrive before clip.created. Do not build a
state machine that depends on arrival order - treat data as the current state
of the resource and apply it idempotently. If you need to reject stale writes,
compare created_at, or re-fetch the resource.

Acknowledge first, work second. Return 2xx as soon as you have durably
recorded the event, then process asynchronously. A handler that renders,
uploads or calls a third party before responding will exceed the 10-second
delivery timeout and generate duplicates.

Any 2xx acknowledges. Anything else, including a redirect, counts as a
failure.

Retries

A delivery is retried when your endpoint returns a non-2xx status, or does not
respond within 10 seconds.

There are 6 attempts in total: the first, then 5 retries spaced 30 seconds,
2 minutes, 10 minutes, 30 minutes and 1 hour after the preceding failure. After
the sixth, the delivery is marked exhausted and is not retried again.

Recovering from missed deliveries

Exhausted deliveries are not lost, and you have three ways to recover:

1. Inspect. GET /webhook-endpoints/{id}/deliveries lists recent attempts
   with response_status, error and next_retry_at. Start here when events
   stop arriving.
2. Replay. POST /webhook-endpoints/deliveries/{deliveryId}/replay
   re-sends the original payload byte-for-byte, including its event id - so a
   correctly deduplicating consumer safely ignores a replay of something it
   already handled.
3. Poll. For job-backed work, GET /jobs/{id} and
   GET /clips/{id}/jobs return the current job state. This is the reliable
   fallback: it lets you reconcile without re-running the render.

Testing your endpoint

POST /webhook-endpoints/{id}/test queues a synthetic event so you can verify
connectivity and your signature check before relying on live traffic. Its
payload carries "test": true and no real resource data, and its job_id and
idempotency_key are always null.