AiVideoEditor
Start for free
Menu

Reviewed 2026-11-11 · API version 2026-11-09 · Read Markdown

Customer webhooks

Outgoing event delivery for your workspace. Register an HTTPS endpoint, verify the one-time signing secret, and receive signed events with bounded retries.

Register an endpoint

curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  $BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
  • The signing secret (whsec_…) is returned once: in the first successful creation response. Store it; an idempotent replay of the same creation returns the endpoint without the secret, and it cannot be shown again.
  • Destinations must be HTTPS, publicly resolvable, and free of embedded credentials. Requests to private, loopback, link-local (including cloud metadata), unique-local and multicast addresses are refused before any connection is made, and redirects are never followed.
  • Registration enqueues a targeted webhook.verification event for that endpoint, independent of its eventTypes filter. Ordinary events flow only after your endpoint answers the verification with 2xx.

Verifying deliveries

Every request carries:

HeaderMeaning
x-publisher-event-idStable event ID: identical across retries and replays
x-publisher-event-typeEvent type, e.g. post.published
x-publisher-timestampUnix seconds
x-publisher-signaturet=<ts>,v1=<hex>

The signature is HMAC-SHA256 over ${t}.${event_id}.${raw_body} using your signing secret. Verify with a ±300 second tolerance and reject replays outside it. Node example:

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

function verify(secret, headers, rawBody) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
  if (!m) return false;
  const [t, v1] = [Number(m[1]), m[2]];
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Always verify against the raw request body before parsing.

Event envelope

{
  "id": "0192d0d0-0000-7000-8000-00000000000f",
  "type": "post.published",
  "createdAt": "2026-11-09T12:00:01Z",
  "apiVersion": "2026-11-09",
  "data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}

Initial event catalog (extensible; eventTypes filters at registration):

  • webhook.verification: challenge payload; answer 2xx to activate the endpoint
  • post.published: one destination confirmed with a native receipt
  • delivery.failed: one destination failed terminally
  • delivery.requires_action: consent/reconnection/late-review required

Aggregate post outcomes (post.partially_published, post.failed) are not emitted yet; they are documented here only once a producer exists, so don't rely on them. Subscribe to the per-destination events above and derive batch state from the post's delivery outcomes.

Retries, replay and disabling

  • Attempts: immediately, then +1m, +5m, +30m, +2h, +8h. Retries reuse the same event ID and byte-identical body so you can deduplicate safely.
  • 2xx = delivered. 429/5xx/timeouts retry. Other 4xx fail permanently for that event (fix the endpoint, then replay).
  • 410 Gone disables the endpoint: no further events are enqueued to it.
  • Operator-authorized replay through the internal webhook service re-sends an event with its original ID. An actively-leased in-flight attempt is never yanked; replay reports that the event is busy and can be retried shortly.

Operational notes

  • Delivery diagnostics store only safe outcome codes: never your secret, signatures, request headers or response bodies. Payloads are additionally sanitized: provider/OAuth secrets and media presign URLs are stripped before anything is queued.
  • Endpoints are workspace-scoped: possession of an endpoint UUID from another workspace does nothing.
  • Delivery is at-least-once per accepted event occurrence; deduplicate on x-publisher-event-id.

Developer tools availability

The Developers page lists workspace API keys and webhook endpoints independently of signing-secret encryption configuration. Creating a webhook requires valid server encryption configuration; ask the deployment operator to resolve a configuration warning. API-key management remains available. Existing signing secrets are never shown again.