Webhooks

Listen for render completion events

Webhooks let your server react to render lifecycle events without polling.

Event types

Event	Fired when
image.completed	Image render reaches completed
image.failed	Image render reaches failed
video.completed	Video render reaches completed
video.failed	Video render reaches failed
collection.completed	All children of a collection finished

Per-render webhooks

Pass webhook_url in the render payload:

{
  "template_id": "tpl_abc",
  "modifications": [...],
  "webhook_url": "https://your.app/hooks/imtegrate"
}

Imtegrate POSTs to that URL once the render is completed or failed.

Org-level webhooks

In Settings → Webhooks, register an endpoint that receives all events for the organization. Useful when you don’t control the request (e.g., dashboard-triggered renders).

Payload

{
  "type": "image.completed",
  "created_at": "2026-05-04T10:01:23Z",
  "data": {
    "id": "img_xyz",
    "status": "completed",
    "result_url": "https://storage.imtegrate.com/...",
    "template_id": "tpl_abc",
    "duration_ms": 3210
  }
}

Signature verification

Each request includes an X-Imtegrate-Signature header — HMAC-SHA256 of the raw body, keyed by the webhook secret shown at creation time.

import crypto from "node:crypto";

function verify(rawBody: string, signature: string, secret: string) {
  const mac = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(signature));
}

Always verify the signature before trusting the payload. Reject any request whose signature doesn’t match.

Retries

Failed deliveries (non-2xx response or timeout) are retried with exponential backoff: 1 min, 5 min, 30 min, 2 h, 12 h. After 5 failed attempts the event is dropped and surfaced in the dashboard.

Idempotency

Each delivery includes X-Imtegrate-Delivery-Id. Treat it as an idempotency key on your side — the same event may be delivered more than once.