Task completion webhooks

Receive POST callbacks when async gateway tasks reach a terminal state (success or fail).

Per-request callback (recommended, Kie.ai-compatible)

Pass callBackUrl at the top level of createTask (same level as model, not inside input). Authenticate with Authorization: Bearer YOUR_API_KEY when creating the task — no ModKie platform webhook secret is required.

{
  "model": "modkie/wan-2.2-i2v",
  "callBackUrl": "https://example.com/api/moddie/webhook",
  "input": { "prompt": "..." }
}

When callBackUrl is set for a task, ModKie POSTs only to that URL when the task completes. The callback is a plain JSON POST (no X-ModKie-Signature header). Account-level subscriptions (below) are not used for that task.

Account-level fallback

If you omit callBackUrl on a task, you can register a default HTTPS endpoint for all tasks on your account:

curl -X POST https://modkie.com/api/gateway/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/modkie","secret":"your-own-optional-secret"}'

The optional secret here is your own value chosen at registration time (not a ModKie platform config). When set, ModKie signs account-level subscription callbacks with X-ModKie-Signature.

Payload

{
  "event": "task.completed",
  "taskId": "task_xxx",
  "state": "success",
  "provider": "kie",
  "capability": "video",
  "model": "google/veo-3-1",
  "result": {
    "video_url": "https://cdn.example.com/gateway-results/.../out.mp4"
  },
  "failMsg": null,
  "creditsCharged": 120,
  "timestamp": "2026-06-26T12:00:00.000Z"
}

On terminal success, ModKie materializes any data: / raw base64 media in result to object storage (R2) before dispatching the webhook. Callbacks therefore carry HTTPS URLs only (no megabyte base64). The same URL-normalized result is returned from recordInfo after settle. Require R2 (or equivalent storage) to be configured in Admin settings.

For account subscriptions with a registered secret, verify X-ModKie-Signature: sha256=<hmac> (HMAC-SHA256 of the raw JSON body). Per-request callBackUrl callbacks are unsigned.

List / delete account subscriptions

• GET /api/gateway/webhooks
• DELETE /api/gateway/webhooks?id={subscriptionId}