Webhook Status Faktur Pajak: Terima NSFP di ERP

Webhook status faktur pajak adalah panggilan HTTP otomatis dari layanan pengiriman ke sistem Anda setiap kali status sebuah faktur berubah, misalnya disetujui DJP dan mendapat Nomor Seri Faktur Pajak (NSFP), atau ditolak beserta alasannya. Dengan webhook, ERP tidak perlu menanyakan status berulang kali. Agar aman dipakai, penerimanya harus memeriksa tanda tangan, tahan terhadap kiriman ganda, dan tidak bergantung pada urutan kedatangan.

Oleh Tim Produk Coretax EOS Teknologi — Diperbarui: 2026-10-29

Poin penting

Webhook memberi tahu ERP saat faktur disetujui atau ditolak. Kirim ulang otomatis terjadi bila penerima gagal merespons.
Periksa tanda tangan HMAC pada body mentah sebelum membaca isi, dan tolak pesan yang cap waktunya terlalu lama.
Anggap setiap pesan bisa datang dua kali dan tidak berurutan. Simpan status berdasarkan waktu pembaruan, bukan urutan kedatangan.
Balas dengan cepat, lalu proses di belakang antrean. Penerima yang lambat bisa dinonaktifkan otomatis.
Siapkan sinkron status berkala sebagai jaring pengaman bila ada pesan yang terlewat.

Mau menguji penerima webhook tanpa menyentuh DJP? Kunci uji EOS Coretax Gateway berjalan di simulator, jadi tim IT dapat mencoba seluruh alur status dengan faktur contoh. Coba lingkungan uji → Pertanyaan soal paket bisa disampaikan lewat tombol WhatsApp di halaman ini.

Apa itu webhook status faktur pajak dan kapan dipicu?

Webhook status faktur pajak adalah pesan HTTP yang dikirim layanan pengiriman ke alamat milik Anda saat status dokumen berubah. Pemicunya meliputi persetujuan DJP yang membawa NSFP, penolakan DJP, kegagalan pengiriman, pembatalan, dan penggantian faktur. ERP membaca pesan itu lalu memperbarui catatan faktur.

Di EOS Coretax Gateway, event utamanya adalah document.approved, document.rejected, document.failed, document.void, dan document.replaced. Ada juga event untuk retur dan faktur masukan. Status dokumen yang bisa muncul meliputi draft, queued, submitting, pending_djp, approved, rejected, failed, cancelled, void_requested, void, dan replaced.

NSFP sendiri kini muncul otomatis saat faktur selesai dibuat dan diajukan. Pejabat DJP menyatakan hal itu pada 25 Oktober 2024, sebagaimana dikutip DDTCNews. Karena nomornya baru diketahui setelah DJP memproses, ERP memerlukan jalur yang andal untuk menerimanya kembali.

Skalanya tidak kecil. Per 12 Januari 2025, baru 564.675 dari 1,51 juta faktur yang dibuat di Coretax yang berstatus terbit, sekitar 37%. Sumber: DDTCNews, 14 Januari 2025.

Bagaimana memverifikasi tanda tangan webhook?

Verifikasi dilakukan dengan menghitung HMAC-SHA256 atas body mentah, memakai rahasia webhook milik Anda, lalu membandingkannya dengan nilai pada header tanda tangan. Di Gateway, header itu bernama X-CTG-Signature, dan pesan dengan cap waktu yang selisihnya lebih dari 5 menit sebaiknya ditolak.

Ada beberapa aturan yang sering terlewat:

Hitung tanda tangan dari body mentah. Jika body sudah diurai dan dirakit ulang, urutan field berubah dan hasilnya tidak cocok.
Bandingkan dengan fungsi perbandingan waktu konstan, bukan operator sama dengan biasa.
Periksa cap waktu untuk menolak pesan lama yang dikirim ulang oleh pihak lain.
Simpan rahasia webhook di penyimpanan rahasia, bukan di kode sumber.

Algoritma HMAC didefinisikan dalam RFC 2104. Format string yang ditandatangani dan contoh kode untuk Node.js, PHP, Python, C#, dan Java ada di dokumentasi API Gateway. Ikuti contoh di sana karena detail format tidak boleh ditebak.

Mengapa penerima webhook harus idempoten?

Penerima harus idempoten karena pesan yang sama bisa tiba lebih dari satu kali dan urutannya tidak dijamin. Pemrosesan kedua dari pesan yang sama tidak boleh mengubah hasil. Gunakan updatedAt pada dokumen untuk memutuskan apakah pesan yang datang lebih baru daripada status yang tersimpan.

Kiriman ganda muncul dari mekanisme kirim ulang. Jika penerima Anda tidak membalas tepat waktu atau membalas galat, Gateway mencoba lagi sampai 6 kali.

Bila gagal beruntun sebanyak 30 kali, endpoint dinonaktifkan otomatis. Penerima yang lambat atau sering galat bisa kehilangan seluruh aliran status.

Sisi pengiriman juga punya perlindungan serupa. Setiap dokumen membawa externalRef yang bekerja sebagai kunci idempotensi. Mengirim ulang isi yang sama mengembalikan hasil "duplicate".

Mengirim isi berbeda dengan kunci yang sama menghasilkan galat 409 E_IDEMPOTENCY. Dengan begitu, percobaan ulang dari ERP saat jaringan putus tidak membuat faktur ganda.

Bagaimana alur penerima yang aman?

Alur yang aman terdiri dari lima langkah: terima body mentah, verifikasi tanda tangan dan cap waktu, simpan pesan ke antrean, balas dengan kode sukses, lalu proses di latar belakang dengan pengecekan updatedAt. Urutan ini menjaga respons tetap cepat dan pemrosesan tetap aman.

text

terima request
  baca body mentah
  hitung HMAC dari body mentah dengan rahasia webhook
  bandingkan dengan header tanda tangan (waktu konstan)
  tolak bila tidak cocok atau cap waktu lebih dari 5 menit
  simpan pesan ke antrean
  balas 2xx segera

pekerja antrean
  ambil pesan
  cari faktur berdasarkan id atau externalRef
  jika updatedAt pesan <= updatedAt tersimpan: abaikan
  jika tidak: perbarui status, NSFP, dan alasan penolakan

Kode di atas bersifat ilustrasi alur, bukan format resmi. Nama field dan cara membentuk string tanda tangan mengikuti dokumentasi API Gateway.

Apa yang dilakukan ERP untuk tiap status?

Setiap status membutuhkan tindakan berbeda di ERP: simpan NSFP bila disetujui, tampilkan alasan bila ditolak, dan tandai untuk dicoba ulang bila gagal karena sebab sementara. Tabel berikut meringkas penanganan yang masuk akal.

Status atau event	Artinya	Tindakan di ERP
`approved`	DJP menyetujui dan memberi NSFP	Simpan NSFP, tandai faktur terbit
`rejected`	DJP menolak	Tampilkan alasan ke staf pajak, koreksi, lalu kirim ulang
`failed`	Pengiriman gagal	Periksa penyebab, coba ulang bila sebabnya sementara
`pending_djp`	Menunggu keputusan DJP	Tunggu, jangan kirim ulang
`void` atau `replaced`	Faktur dibatalkan atau diganti	Perbarui catatan dan hubungkan ke faktur pengganti

Penolakan paling sering berakar pada data, misalnya NITKU atau identitas pembeli yang tidak cocok. Penyebab dan cara memperbaikinya dibahas di Error Import Faktur Coretax. Memeriksa data sebelum dikirim dibahas di Validasi Data Coretax.

Kapan sinkron status berkala masih diperlukan?

Sinkron berkala tetap diperlukan sebagai jaring pengaman, sebab webhook bisa terlewat bila penerima mati lebih lama dari masa kirim ulang. Jalankan sinkron terjadwal untuk mencocokkan status semua faktur yang belum final, lalu perbaiki yang berbeda.

Faktur dengan status belum final, seperti queued, submitting, dan pending_djp, menjadi sasaran utama. Tentukan umur maksimum faktur di status tersebut, dan beri peringatan bila terlampaui. Untuk volume besar, perhatikan juga batas 300 permintaan per menit per kunci, maksimal 500 baris per faktur, dan 1 sampai 100 faktur per permintaan pembuatan dokumen.

Jika Anda masih mengirim faktur lewat file XML, batas dari DJP berbeda: satu file bisa memuat 1.000 faktur, dengan penandatanganan bertahap 500 faktur per unggahan menurut DDTCNews. Gambaran jalur otomatis dari ERP secara umum ada di CoreTax Host-to-Host ERP.

Siap menguji penerima webhook Anda? Buat akun uji gratis → atau pelajari layanan EOS Coretax Gateway dan diskusikan kebutuhan integrasi dengan tim EOS lewat tombol WhatsApp di halaman ini.

Pertanyaan Umum tentang Webhook Status Faktur Pajak

Apakah webhook menjamin setiap status sampai ke ERP?

Tidak sepenuhnya. Pesan bisa terlambat, ganda, atau tidak berurutan, dan penerima yang mati lama bisa melewatkannya. Karena itu webhook perlu dipasangkan dengan sinkron status berkala.

Berapa kali pesan webhook dikirim ulang?

Gateway mencoba ulang sampai 6 kali bila pengiriman gagal. Setelah 30 kegagalan beruntun, endpoint dinonaktifkan otomatis dan perlu Anda aktifkan kembali setelah masalahnya diperbaiki.

Mengapa tanda tangan harus dihitung dari body mentah?

Karena tanda tangan dibuat atas byte yang persis dikirim. Jika body diurai lalu dirakit ulang, susunannya bisa berubah dan hasil hitungannya tidak lagi cocok, walaupun isinya sama.

Apa yang terjadi bila ERP mengirim faktur yang sama dua kali?

Jika isinya sama dan memakai externalRef yang sama, Gateway mengembalikan hasil "duplicate" dan tidak membuat faktur baru. Jika isinya berbeda dengan kunci yang sama, hasilnya galat 409 E_IDEMPOTENCY.

Apakah kunci uji mengirim webhook sungguhan?

Kunci uji berjalan di simulator dan tidak pernah menyentuh DJP, jadi Anda bisa menguji alur status dengan faktur contoh. Kunci live baru aktif setelah NPWP dan penandatangan diverifikasi.

Apakah saya perlu membuat penerima webhook sendiri?

Perlu bila Anda ingin status kembali otomatis ke ERP. Jika tim Anda memakai CoreTax Studio sebagai jalur pengirim, status bisa dipantau dari portal tanpa membangun penerima sendiri.

Ditinjau oleh: Tim Teknologi EOS Teknologi. Rujukan: Peraturan Menteri Keuangan Nomor 81 Tahun 2024 tentang Ketentuan Perpajakan dalam Rangka Pelaksanaan Sistem Inti Administrasi Perpajakan, dan dokumentasi API EOS Coretax Gateway.