Webhooks

Task completion webhooks

Register an HTTPS endpoint to receive POST callbacks when async gateway tasks reach a terminal state (success or fail).

Register

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":"optional-signing-secret"}'

Payload

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

When secret is set, verify header X-ModKie-Signature: sha256=<hmac> (HMAC-SHA256 of the raw JSON body).

List / delete

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

On this page

Task completion webhooks