API Webhook - CBT Indolat

Seluruh request pengelolaan webhook membutuhkan Bearer API Key.

Endpoint webhook

Event yang tersedia:

exam_participant.registered — peserta didaftarkan ke ujian
exam_participant.unregistered — pendaftaran peserta dibatalkan
exam_result.completed — peserta selesai mengerjakan tes
exam_result.scored — nilai tes terbit atau berubah
question_import.completed — import paket soal selesai
question_import.failed — import paket soal gagal

Webhook hanya dikirim selama add-on Integrasi API aktif dan endpoint dalam keadaan aktif.

Kapan event dikirim

exam_participant.registered dikirim untuk pendaftaran melalui API dan melalui panel. Pendaftaran mandiri peserta lewat halaman pendaftaran ujian tidak mengirim event ini.
exam_participant.unregistered dikirim saat pendaftaran dibatalkan melalui API.
exam_result.completed dan exam_result.scored berasal dari pemindaian hasil ujian yang berjalan setiap menit, sehingga event dapat tiba sekitar 1–2 menit setelah peserta selesai.
exam_result.completed dapat membawa score: null untuk tes yang dinilai dengan IRT atau secara manual. exam_result.scored menyusul setelah nilainya dihitung.
exam_result.scored dikirim lagi setiap kali score atau meta_score berubah, misalnya setelah perhitungan ulang IRT atau perhitungan ulang skor. Nilai yang sama tidak dikirim dua kali.
question_import.completed dan question_import.failed dikirim saat import paket soal lewat API Import Soal selesai atau gagal.
Urutan kedatangan event tidak dijamin. Gunakan updated_at dari API Hasil Ujian untuk menentukan data terbaru, dan sinkronkan ulang secara berkala dengan GET /exam-results?updated_since=... agar event yang terlewat tetap tertangani.

GET /webhooks — Daftar endpoint webhook

Parameter

Tidak ada parameter endpoint.

Contoh request

curl -X GET "https://app.indolat.com/api/v1/webhooks" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json"

Contoh response

{
  "success": true,
  "message": null,
  "data": [
    {
      "id": 5,
      "url": "https://integrasi.example.com/webhooks/cbt",
      "description": "Webhook hasil ujian",
      "events": ["exam_result.completed", "exam_result.scored"],
      "is_active": true,
      "is_disabled_by_system": false,
      "disabled_at": null,
      "consecutive_failures": 0,
      "last_success_at": "2026-08-02T12:00:00+07:00",
      "last_failure_at": null,
      "created_at": "2026-07-01T08:00:00+07:00"
    }
  ],
  "meta": {
    "available_events": {
      "exam_participant.registered": "Peserta didaftarkan ke ujian",
      "exam_participant.unregistered": "Peserta dibatalkan dari ujian",
      "exam_result.completed": "Peserta selesai mengerjakan tes",
      "exam_result.scored": "Nilai tes terbit atau berubah",
      "question_import.completed": "Import paket soal selesai",
      "question_import.failed": "Import paket soal gagal"
    }
  }
}

POST /webhooks — Mendaftarkan endpoint webhook

Maksimal lima endpoint webhook per projek; endpoint keenam ditolak dengan status 409. Signing secret hanya dikembalikan saat endpoint dibuat atau secret dirotasi.

Parameter

Nama	Lokasi	Wajib	Tipe	Keterangan
`url`	Body	Ya	URL	URL HTTP/HTTPS penerima webhook, maksimal 2.048 karakter. HTTPS direkomendasikan.
`events`	Body	Ya	string[]	Minimal satu event yang tersedia.
`events.*`	Body	Ya	enum	Nama event webhook yang valid.
`description`	Body	Tidak	string/null	Deskripsi, maksimal 255 karakter.
`is_active`	Body	Tidak	boolean	Default `true`.

Contoh request

curl -X POST "https://app.indolat.com/api/v1/webhooks" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://integrasi.example.com/webhooks/cbt",
    "description": "Webhook hasil ujian",
    "events": ["exam_result.completed", "exam_result.scored"],
    "is_active": true
  }'

Contoh response

{
  "success": true,
  "message": "Endpoint webhook berhasil dibuat. Simpan secret ini — nilainya tidak dapat dilihat kembali.",
  "data": {
    "id": 5,
    "url": "https://integrasi.example.com/webhooks/cbt",
    "description": "Webhook hasil ujian",
    "events": ["exam_result.completed", "exam_result.scored"],
    "is_active": true,
    "is_disabled_by_system": false,
    "disabled_at": null,
    "consecutive_failures": 0,
    "last_success_at": null,
    "last_failure_at": null,
    "created_at": "2026-08-03T10:00:00+07:00",
    "secret": "whsec_a1b2c3d4e5f6..."
  }
}

PATCH /webhooks/{id} — Memperbarui endpoint webhook

Endpoint juga menerima metode PUT. Secret baru hanya dikembalikan jika rotate_secret bernilai true. Mengirim is_active: true juga mengaktifkan kembali endpoint yang dinonaktifkan otomatis oleh sistem dan mengatur ulang consecutive_failures ke 0.

Parameter

Nama	Lokasi	Wajib	Tipe	Keterangan
`id`	Path	Ya	integer	ID endpoint webhook.
`url`	Body	Tidak	URL	URL HTTP/HTTPS baru, maksimal 2.048 karakter.
`events`	Body	Tidak	string[]	Minimal satu event jika field dikirim.
`events.*`	Body	Kondisional	enum	Wajib pada setiap item `events`.
`description`	Body	Tidak	string/null	Deskripsi baru, maksimal 255 karakter.
`is_active`	Body	Tidak	boolean	Aktif/nonaktifkan endpoint.
`rotate_secret`	Body	Tidak	boolean	Buat signing secret baru. Default `false`.

Contoh request

curl -X PATCH "https://app.indolat.com/api/v1/webhooks/5" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["exam_result.completed"],
    "is_active": true,
    "rotate_secret": true
  }'

Contoh response

{
  "success": true,
  "message": "Endpoint diperbarui. Simpan secret baru ini — nilainya tidak dapat dilihat kembali.",
  "data": {
    "id": 5,
    "url": "https://integrasi.example.com/webhooks/cbt",
    "description": "Webhook hasil ujian",
    "events": ["exam_result.completed"],
    "is_active": true,
    "is_disabled_by_system": false,
    "disabled_at": null,
    "consecutive_failures": 0,
    "last_success_at": "2026-08-02T12:00:00+07:00",
    "last_failure_at": null,
    "created_at": "2026-07-01T08:00:00+07:00",
    "secret": "whsec_secret_baru..."
  }
}

DELETE /webhooks/{id} — Menghapus endpoint webhook

Parameter

Nama	Lokasi	Wajib	Tipe	Keterangan
`id`	Path	Ya	integer	ID endpoint webhook.

Contoh request

curl -X DELETE "https://app.indolat.com/api/v1/webhooks/5" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json"

Contoh response

{
  "success": true,
  "message": "Endpoint webhook berhasil dihapus.",
  "data": null
}

GET /webhooks/{id}/deliveries — Riwayat pengiriman webhook

Parameter

Nama	Lokasi	Wajib	Tipe	Keterangan
`id`	Path	Ya	integer	ID endpoint webhook.
`event`	Query	Tidak	enum	Filter nama event.
`status`	Query	Tidak	enum	Filter status delivery: `pending` (menunggu atau sedang dicoba ulang), `delivered`, atau `failed`.
`page`	Query	Tidak	integer	Nomor halaman. Default `1`.
`per_page`	Query	Tidak	integer	Data per halaman, `1–100`. Default `25`.

Contoh request

curl -X GET "https://app.indolat.com/api/v1/webhooks/5/deliveries?event=exam_result.completed&status=delivered&page=1&per_page=25" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json"

Contoh response

{
  "success": true,
  "message": null,
  "data": [
    {
      "id": "9f48da6d-39b8-4cf2-b4dd-b62d9592b7e4",
      "event": "exam_result.completed",
      "status": "delivered",
      "attempts": 1,
      "response_code": 200,
      "response_body": "OK",
      "error_message": null,
      "payload": {
        "event": "exam_result.completed",
        "created_at": "2026-08-10T09:20:00+07:00",
        "data": { "exam_result_id": 9812, "participant_code": "TPA0000021", "score": 82.5 }
      },
      "delivered_at": "2026-08-10T09:20:02+07:00",
      "created_at": "2026-08-10T09:20:00+07:00"
    }
  ],
  "meta": {
    "pagination": { "total": 1, "per_page": 25, "current_page": 1, "last_page": 1, "from": 1, "to": 1 }
  }
}

POST /webhooks/{id}/test — Mengirim webhook percobaan

Jika event tidak dikirim atau tidak dikenali, event default adalah exam_result.completed. Pengiriman uji coba memakai nama event yang dipilih dan signature yang sama dengan pengiriman asli, tetapi isi data berupa pesan uji coba: { "message": "...", "sent_at": "..." }. Endpoint yang sedang nonaktif ditolak dengan status 409.

Parameter

Nama	Lokasi	Wajib	Tipe	Keterangan
`id`	Path	Ya	integer	ID endpoint webhook yang aktif.
`event`	Body	Tidak	enum	Event yang akan disimulasikan. Default `exam_result.completed`.

Contoh request

curl -X POST "https://app.indolat.com/api/v1/webhooks/5/test" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "event": "exam_result.completed" }'

Contoh response

{
  "success": true,
  "message": "Pengiriman uji coba telah diantrekan.",
  "data": { "queued": true }
}

Payload dan signature webhook

Setiap webhook dikirim sebagai POST dengan body JSON berisi event, created_at (waktu event diantrekan), dan data. Body yang sama dikirim ulang apa adanya pada setiap percobaan ulang.

Header	Keterangan
`Content-Type`	`application/json`.
`X-Cbt-Event`	Nama event, misalnya `exam_result.completed`.
`X-Cbt-Delivery`	ID pengiriman (UUID). Nilainya sama pada setiap percobaan ulang dan sama dengan `id` pada riwayat pengiriman. Gunakan untuk mengabaikan pengiriman ganda.
`X-Cbt-Signature`	Signature dengan format `t=<unix>,v1=<hex>`.

Payload `exam_result.completed` dan `exam_result.scored`

Kedua event memakai struktur data yang sama. Isi meta_score pada setiap metode penilaian dijelaskan pada bagian Struktur meta_score di API Hasil Ujian.

{
  "event": "exam_result.completed",
  "created_at": "2026-08-10T09:21:00+07:00",
  "data": {
    "exam_result_id": 9812,
    "user_result_exam_uuid": "9f1c2a2d-9739-4c2f-9a94-312a9cc1b4ad",
    "user_exam_id": 4410,
    "participant_code": "TPA0000021",
    "exam": { "id": 12, "name": "Tes Masuk 2026", "name_short": "TPA" },
    "exam_quiz": { "id": 45, "name": "Tes Potensi Akademik" },
    "participant": { "id": 340, "name": "Budi Santoso", "email": "budi@sekolah.sch.id" },
    "status": 2,
    "status_label": "Selesai Ujian",
    "score": 82.5,
    "meta_score": { "correct": 33, "incorrect": 7, "unanswered": 0 },
    "start_at": "2026-08-10T08:05:00+07:00",
    "end_at": "2026-08-10T09:20:00+07:00"
  }
}

Payload `exam_participant.registered`

{
  "event": "exam_participant.registered",
  "created_at": "2026-08-03T10:00:00+07:00",
  "data": {
    "user_exam_id": 4410,
    "participant_code": "TPA0000021",
    "exam": { "id": 12, "name": "Tes Masuk 2026", "name_short": "TPA" },
    "participant": { "id": 340, "name": "Budi Santoso", "email": "budi@sekolah.sch.id" },
    "registered_at": "2026-08-03T10:00:00+07:00"
  }
}

Payload `exam_participant.unregistered`

{
  "event": "exam_participant.unregistered",
  "created_at": "2026-08-04T09:00:00+07:00",
  "data": {
    "user_exam_id": 4410,
    "participant_id": 340,
    "exam": { "id": 12, "name": "Tes Masuk 2026", "name_short": "TPA" },
    "unregistered_at": "2026-08-04T09:00:00+07:00"
  }
}

Verifikasi signature

v1 adalah HMAC-SHA256 dari <t>.<raw body> menggunakan signing secret endpoint. Nilai t dibuat ulang pada setiap percobaan pengiriman. Tolak request yang signature-nya tidak cocok atau yang t-nya berselisih lebih dari 300 detik dari waktu server Anda.

[$timestamp, $signature] = sscanf(
    $request->header('X-Cbt-Signature'),
    't=%d,v1=%s',
);

$expected = hash_hmac(
    'sha256',
    $timestamp.'.'.$request->getContent(),
    $secret,
);

if (! hash_equals($expected, $signature) || abs(time() - $timestamp) > 300) {
    abort(400);
}

Percobaan ulang

Balas webhook dengan status 2xx dalam 10 detik. Simpan event terlebih dahulu, lalu proses di latar belakang.
Respons selain 2xx, timeout, atau kegagalan koneksi dicoba ulang sampai total 4 kali percobaan, dengan jeda 1 menit, 5 menit, lalu 30 menit. Setelah percobaan terakhir gagal, status pengiriman menjadi failed.
Endpoint yang gagal 10 kali berturut-turut dinonaktifkan otomatis (is_disabled_by_system: true), dan pemilik projek menerima notifikasi di panel. Aktifkan kembali dengan PATCH /webhooks/{id} berisi is_active: true setelah endpoint diperbaiki.
Pengiriman yang sudah berstatus failed tidak dikirim ulang. Gunakan GET /exam-results?updated_since=... untuk mengambil hasil yang terlewat.

​Endpoint webhook

​Kapan event dikirim

​Parameter

​Contoh request

​Contoh response

​Parameter

​Contoh request

​Contoh response

​Parameter

​Contoh request

​Contoh response

​Parameter

​Contoh request

​Contoh response

​Parameter

​Contoh request

​Contoh response

​Parameter

​Contoh request

​Contoh response

​Payload dan signature webhook

​Header

​Payload exam_result.completed dan exam_result.scored

​Payload exam_participant.registered

​Payload exam_participant.unregistered

​Verifikasi signature

​Percobaan ulang

Endpoint webhook

Kapan event dikirim

Parameter

Contoh request

Contoh response

Parameter

Contoh request

Contoh response

Parameter

Contoh request

Contoh response

Parameter

Contoh request

Contoh response

Parameter

Contoh request

Contoh response

Parameter

Contoh request

Contoh response

Payload dan signature webhook

Header

Payload `exam_result.completed` dan `exam_result.scored`

Payload `exam_participant.registered`

Payload `exam_participant.unregistered`

Verifikasi signature

Percobaan ulang