Webhooks

Webhooks notify your server when an async job (generation, video import, publish, translation) completes or fails.

Delivery targets

There are two ways to receive webhooks:

1. Per-request callbackUrl — pass a callbackUrl in the request body when starting a job. Optionally pass a callbackSecret to enable signature verification (see below). The webhook fires once when the job reaches completed or failed.

2. Project webhook URL — configure a URL in Settings → API Keys & Webhooks → Webhook URL. This URL receives all job events for the project.

Payload shape

{
  "jobId": "uuid",
  "type": "generate",
  "status": "completed",
  "output": { ... },
  "error": null,
  "createdAt": "2026-06-01T10:00:00Z",
  "completedAt": "2026-06-01T10:01:30Z"
}

status is either completed or failed. On failure, error contains a message string and output is null.

Signature verification

When you provide a callbackSecret with your callbackUrl, every delivery includes an X-Hinto-Signature header. The value is the HMAC-SHA256 hex digest of the raw JSON body, signed with your secret.

Verify it in Node.js:

const crypto = require('crypto')

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body) // raw Buffer or string — do not parse JSON first
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

// In your Express handler:
app.post('/webhook', (req, res) => {
  const sig = req.headers['x-hinto-signature']
  const valid = verifySignature(req.rawBody, sig, process.env.CALLBACK_SECRET)
  if (!valid) return res.status(401).send('Invalid signature')
  // handle req.body
  res.sendStatus(200)
})

Note: Project-level webhooks (configured in Settings) do not currently support signing. Signature verification only applies to per-request callbackUrl + callbackSecret pairs.

Example: generation with callback

curl -X POST https://app.hintoai.com/api/external/v2/generate \
  -H "X-API-Key: hinto_..." \
  -H "Content-Type: application/json" \
  -d '{
    "videoId": "video-uuid",
    "callbackUrl": "https://yourapp.com/webhook",
    "callbackSecret": "your-secret"
  }'

Your server receives a POST to https://yourapp.com/webhook when the job finishes.