Webhooks

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.

Get started

Concepts

Guides

Event types

Per-render webhooks

Org-level webhooks

Payload

Signature verification

Retries

Idempotency

​Event types

​Per-render webhooks

​Org-level webhooks

​Payload

​Signature verification

​Retries

​Idempotency

Event types

Per-render webhooks

Org-level webhooks

Payload

Signature verification

Retries

Idempotency