Langsung ke konten utama
Integrasi Webhooks ditujukan untuk developer. Integrasi ini mengirim event JSON ke alamat HTTPS pilihan Anda setiap kali sesuatu terjadi di Foliant. Dengan begitu, sistem Anda sendiri dapat merespons, misalnya dengan mengarsipkan setiap PDF faktur atau mengambil ekspor yang sudah selesai. Webhooks masih dalam tahap beta. Jika Anda tidak melihatnya di Pengaturan › Integrasi, fitur ini belum tersedia untuk toko Anda. Hubungi dukungan untuk menanyakan akses.

Event

Hubungkan webhook

  1. Di Foliant, buka Pengaturan › Integrasi.
  2. Di Webhooks, klik Hubungkan.
  3. Isi pengaturannya:
  4. Klik Hubungkan.
Anda dapat mengubah URL, secret, dan event nanti di Pengaturan pada halaman integrasi.

Isi setiap permintaan

Foliant mengirim permintaan POST dengan body JSON:

Data document.generated

  • template: uuid dan name template.
  • document_type: invoice, credit_note, quote, atau kosong untuk dokumen lain.
  • order: id, name, dan type pesanan (pesanan atau draf pesanan).
  • refund_id dan fulfillment_id, jika dokumen tersebut untuk pengembalian dana atau pengiriman.
  • document_number dan issued_at, untuk dokumen bernomor.
  • source: cara dokumen dibuat, misalnya download, admin_download, export, atau email.
  • export: ID ekspor, jika dokumen tersebut bagian dari ekspor.
  • generated_at.

Data export.completed

  • export: uuid, order_type, template_uuids, jumlah orders, orders_skipped (dihapus setelah dipilih) dan documents, requested_by (merchant atau customer), serta completed_at.
  • download_url: tautan untuk mengunduh ekspor, dan download_url_expires_at, waktu tautan tersebut berhenti berfungsi.
  • download_expires_at: waktu ekspor itu sendiri kedaluwarsa.
Event berisi ID dan jumlah, bukan alamat email pelanggan.

Periksa tanda tangan

Tanda tangan adalah HMAC-SHA256 dalam format hex dari timestamp, sebuah titik, dan body permintaan mentah (<timestamp>.<body>), dengan signing secret Anda sebagai kuncinya. Hitung tanda tangan di sisi Anda, lalu bandingkan dengan nilai setelah sha256= di X-Foliant-Signature. Gunakan body mentah persis seperti yang diterima.

Respons dan percobaan ulang

  • Setiap respons 2xx dianggap terkirim.
  • Jika endpoint Anda mengembalikan error 5xx, 408 atau 429, atau tidak merespons dalam 10 detik, Foliant akan mencoba lagi nanti dengan jeda yang makin lama setiap kali, hingga 5 kali percobaan.
  • Respons 4xx lainnya bersifat final: Foliant tidak mencobanya lagi.
  • Setiap event dikirim satu kali per dokumen atau ekspor. Percobaan ulang tidak pernah mengirimnya dua kali setelah berhasil.
Setiap pengiriman ditampilkan di Aktivitas pada halaman integrasi. Di sana Anda dapat memilih Coba lagi untuk pengiriman yang gagal. Lihat Aktivitas integrasi.

Artikel terkait