Webhooks

Kirim callback_url saat Anda membuat task:

{
  "model": "image-generator",
  "input": { "prompt": "..." },
  "callback_url": "https://client.example.com/webhooks/mager"
}

Mager mengirim satu POST ke URL tersebut begitu task mencapai finished atau failed.

Payload-nya

{
  "event": "generation.finished",
  "task_id": "cmagr01hxyz123",
  "status": "finished",
  "model": "image-generator",
  "result": [
    {
      "id": "result_01hxyz",
      "status": "SUCCESS",
      "file_url": "https://cdn.example.com/generated-image.png",
      "file_type": "image/png"
    }
  ],
  "error": null,
  "created_at": "2026-07-03T06:00:00.000Z",
  "completed_at": "2026-07-03T06:01:00.000Z"
}

event bernilai generation.finished atau generation.failed. Saat gagal, error membawa alasannya dan result kosong.

Permintaan dikirim dengan content-type: application/json dan user agent Mager-Developer-Webhooks/1.0.

Meresponsnya

Kembalikan status 2xx apa pun dalam 10 detik. Selain itu — status non-2xx, timeout, atau kesalahan koneksi — dihitung sebagai pengiriman yang gagal.

Konfirmasi dulu, kerjakan kemudian. Tulis payload-nya ke tempat yang tahan lama, kembalikan 200, lalu lakukan pengunduhan dan pemrosesan di waktu Anda sendiri. Handler yang mengunduh file sebelum merespons adalah penyebab paling umum retry akibat timeout.

Retry

Pengiriman yang gagal diulang sampai 3 percobaan total, berjarak 60 detik. Setelah kegagalan ketiga, pengiriman ditandai FAILED dan Mager berhenti.

Status pengiriman terlihat pada task itu sendiri, di bawah webhooks:

{
  "id": "delivery_01hxyz",
  "status": "RETRYING",
  "attempts": 2,
  "max_attempts": 3,
  "last_attempt_at": "2026-07-03T06:02:00.000Z",
  "next_retry_at": "2026-07-03T06:03:00.000Z",
  "last_status_code": 502,
  "last_error": "Request failed with status code 502"
}

Kalau endpoint Anda mati sepanjang jendela retry, antrikan pengiriman baru secara manual:

curl https://api.mageran.ai/api/v1/generation-tasks/cmagr01hxyz123/webhooks/retry \
  --request POST \
  --header 'x-mager-api-key: YOUR_API_KEY'

Task tersebut harus milik akun Anda, harus punya callback_url, dan harus sudah berstatus final.

Mengamankan endpoint Anda

Mager tidak menandatangani permintaan webhook. Tidak ada shared secret dan tidak ada header signature, jadi endpoint Anda tidak bisa memastikan dari permintaannya saja bahwa Mager yang mengirim.

Dua hal yang bisa dilakukan:

1. Selipkan secret di dalam URL. Pakai path atau nilai query yang panjang dan sulit ditebak — https://client.example.com/webhooks/mager/8f2c… — lalu tolak apa pun yang tidak cocok. Kasar, tapi cukup untuk menahan siapa pun yang belum punya URL-nya.
2. Verifikasi sebelum percaya. Perlakukan payload sebagai petunjuk, bukan fakta. Panggil GET /generation-tasks/{taskId} dengan API key Anda dan jadikan response itu sumber kebenaran. Ini sekaligus menangani kasus pengiriman ganda: retry setelah timeout bisa datang untuk task yang sudah Anda proses.

Rancang handler-nya agar idempoten. Memakai task_id sebagai kunci sudah cukup.

Kapan memakai yang mana