Webhooks

Job completions and account events at your URL, signed with x-instadata-signature.

Register a webhook on the Webhooks page or through the API. The response includes a signing secret (whsec_…), shown once.

curl -X POST "https://api.instadata.dev/v1/webhooks" \
  -H "Authorization: Bearer ik_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/instadata", "events": ["job.completed", "credits.low"]}'

Events

EventFires when
job.completedAn async job succeeds or fails
credits.lowThe balance crosses the low-credit threshold
plan.changedThe subscription is upgraded, downgraded or cancelled

Verify the signature

Every delivery carries x-instadata-signature: t=<unix>,v1=<hex>: an HMAC-SHA256 of "{t}.{raw_body}" with the whsec_ secret.

import crypto from "node:crypto";

export function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Compute the HMAC over the raw request body, before JSON parsing, and reject timestamps older than a few minutes.

Delivery

Deliveries expect a 2xx within 10 seconds; anything else is retried with backoff for up to 24 hours. Events carry an id, so treat processing as idempotent.