Dalam menggabungkan animasi 9.300 stasiun kereta Jepang berdasarkan tahun pembukaan dari dataset JIVX, API kontrak webhook wajib menjawab pertanyaan dasar: bagaimana memastikan data historis yang terus bertambah dapat diterima secara akurat oleh mitra sinkronisasi tanpa kehilangan urutan atau menduplikasi update. Kontrak ini harus menetapkan schema respons yang konsisten, penanda versi (timestamp), serta mekanisme filter dan offset untuk permintaan snapshot awal dan incremental selanjutnya.

1. Menetapkan Schema Respons dan Timestamp Versi

Respons webhook harus cukup kaya untuk menjelaskan status setiap stasiun sambil memudahkan pemrosesan di sisi penerima. Gunakan struktur JSON yang menyertakan:

  • station_id: kode unik stasiun.
  • opened_year: tahun pembukaan, sesuai dengan animasi JIVX.
  • status: enum (misalnya active, renovated, closed).
  • history_version: timestamp versi untuk deteksi perubahan.
  • metadata: ringkasan sumber atau catatan tambahan.

Schema ringan tetapi eksplisit penting agar klien dapat validasi payload tanpa asumsi tambahan. Sertakan contoh JSON Schema sederhana sebagai kontrak:

{
  "type": "object",
  "required": ["station_id", "opened_year", "history_version"],
  "properties": {
    "station_id": {"type": "string"},
    "opened_year": {"type": "integer"},
    "status": {"type": "string", "enum": ["active", "renovated", "closed"]},
    "history_version": {"type": "string", "format": "date-time"},
    "metadata": {"type": "object"}
  }
}

Gunakan history_version sebagai timestamp yang mencerminkan versi data (misalnya waktu update data internal). Ini memungkinkan webhook penerima memicu sekali jika menerima event dengan timestamp yang sama dan memastikan ordering.

2. Strategi Snapshot & Incremental

Sinkronisasi historis membutuhkan dua mode: snapshot awal yang mengambil seluruh dataset (9.300 stasiun) dan incremental untuk update selanjutnya.

Snapshot

Permintaan snapshot harus mendukung parameter since dan limit untuk memecah dataset besar menjadi batch. Gunakan offset atau pagination berbasis cursor agar klien bisa melanjutkan jika permintaan terputus.

GET /api/v1/stations/snapshot?since=1889-01-01T00:00:00Z&limit=500&offset=0

Setiap respons menyertakan next_offset sehingga klien tahu kapan harus mengambil batch berikutnya tanpa mengandalkan state eksternal.

Incremental

Untuk incremental, gunakan filter updated_since berdasarkan history_version. Server mengirimkan events terbaru dan klien menyimpan timestamp terakhir yang diproses.

GET /api/v1/stations/changes?updated_since=2024-06-01T00:00:00Z

Respons dapat menyertakan has_more bila perubahan besar perlu diproses bergelombang.

Pastikan order events mengikuti timeline history_version untuk memudahkan rekonsiliasi status stasiun dalam animasi.

3. Lapisan Autentikasi dan Signed Payload

Webhook penerima harus dapat memverifikasi bahwa payload berasal dari sumber tepercaya. Implementasi praktis:

  • Server mengeluarkan API key per partner untuk header X-Api-Key.
  • Payload diberi signature HMAC atas body + timestamp dengan secret tertanam pada server dan penerima.
  • Header tambahan X-Signature dan X-Signed-Timestamp memastikan timestamp tidak replay.
X-Api-Key: partner-rail
X-Signed-Timestamp: 2024-10-20T08:48:00Z
X-Signature: sha256=abracadabra

Penerima memverifikasi signature dengan menyediakan body yang diterima, timestamp, dan secret yang sama. Jika validasi gagal atau timestamp sudah kadaluarsa (misalnya lebih dari 5 menit), webhook menolak dengan 401 untuk mencegah replay attack.

4. Idempotensi, Ordering, dan Retry/Backoff

Untuk mencegah update duplikasi atau kehilangan urutan:

  • Idempotensi: Sertakan event_id unik pada setiap payload. Penerima menyimpan event_id dalam cache terbatas guna mengabaikan duplikat.
  • Ordering: Gunakan history_version sebagai urutan kronologis. Jika server mengirim event non-sekansial, penerima harus buffer sampai versi sebelumnya diproses.
  • Retry & Backoff: Server webhook harus mendeteksi kegagalan (misalnya status 5xx). Terapkan strategi retry eksponensial dengan cap, dan sertakan header Retry-After untuk memberi waktu recovery.

Contoh mekanisme idempotensi sederhana:

if processed_event_ids.contains(event_id):
    return 200
process(payload)
processed_event_ids.add(event_id)

Gunakan struktur data yang memudahkan pembersihan bergantung pada TTL agar cache tidak terus tumbuh. Ordering juga menghindari gap temporal yang dapat merusak animasi timeline stasiun.

5. Observabilitas dan Logging Edge Case

Karena animasi mencerminkan status historis yang unik, penting adanya observabilitas untuk kasus-kasus langka:

  • Catat setiap perubahan status (active ke renovated) beserta history_version dan event_id.
  • Log mismatch antara history_version yang diharapkan dan yang diterima (misalnya versi sebelumnya belum selesai tapi versi baru tiba).
  • Tandai permintaan snapshot yang terputus atau menyebabkan duplikasi offset.

Integrasi observabilitas bisa menggunakan centralized logging (misalnya ELK) dan metric khusus seperti:

  • webhook.delivery.failures
  • snapshot.pagination.errors
  • incremental.latency.ms

Dengan metrik dan log yang jelas, tim dapat menyelidiki edge case seperti event lama tiba setelah snapshot selesai atau perubahan data stasiun yang dilewatkan akibat timeout.

Kesimpulan

Merancang API kontrak webhook untuk sinkronisasi data historis 9.300 stasiun kereta Jepang menuntut schema respons tepat, pencatatan versi timestamp, serta pengaturan snapshot dan incremental yang bisa diulang. Lapisan autentikasi berbasis API key dan signed payload memastikan keaslian data, sementara idempotensi, ordering, dan retry/backoff menjaga integritas update. Observabilitas yang kuat membantu mendeteksi edge case sebelum memengaruhi visualisasi animasi timeline stasiun.