Webhooks

Webhooks notify your HTTPS endpoint when a generation finishes, so you do not have to poll continuously.

Setup

1. In the dashboard, add a webhook URL (HTTPS recommended).
2. Store the webhook secret shown for that endpoint (used for signature verification).
3. Ensure your endpoint accepts POST and returns 2xx after you have accepted the event.

Webhook URLs are not configured via the Integration API; use the dashboard.

Events

Envelope shape (customer body after delivery):

• job_id
• user_id
• event_type
• data — job snapshot (includes output_url on success, error on failure)

Exact field schemas for both events: API Reference — Webhooks. Prefer that page as the schema source of truth.

Headers

Verify the signature

Compute HMAC-SHA256 over the raw body bytes with your webhook secret, hex-encode the digest, and compare to the value after sha256= in X-DrapeItOn-Signature. Use a constant-time comparison.

Example (Node.js):

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

function verifyDrapeItOnSignature(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const match = /^sha256=([a-f0-9]+)$/i.exec(signatureHeader || "");
  if (!match) return false;
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(match[1], "hex");
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

Reject requests that fail verification.

Delivery behavior

• Acknowledge with HTTP 2xx as soon as you have safely accepted the event (process heavy work asynchronously if needed).
• Failed deliveries are retried automatically with backoff. Exact retry counts and timing may change; the API Reference — Webhooks description states the current public detail.
• Delivery stops without further retries if your endpoint responds with one of: 400, 401, 403, 404, 410, 501.
• Other non-2xx responses and network failures are treated as retryable until the platform stops retrying.
• Deliveries may be at-least-once — make handlers idempotent on job_id + event_type.

Related

• Handling results
• API Reference