Cara menggunakan webhook di Postoria

Webhook Postoria mengirimkan hasil penerbitan postingan yang telah selesai ke endpoint HTTPS publik yang Anda kelola. Gunakan webhook untuk memperbarui pelacak internal, mencatat tautan postingan yang sudah terbit di CMS Anda, atau memulai alur kerja lanjutan setelah percobaan penerbitan selesai.

Webhook tersedia pada semua paket, termasuk Free. Fitur ini berlaku untuk postingan yang dibuat di aplikasi Postoria maupun melalui integrasi.

Sebelum memulai

  • Anda dapat mengatur satu URL webhook per profil. URL ini menerima peristiwa yang dipilih dari semua ruang kerja milik Anda, termasuk ruang kerja yang sedang tidak Anda buka.
  • Ruang kerja tempat Anda hanya menjadi anggota tim tidak disertakan. Pemiliknya mengelola pengaturan webhook untuk ruang kerja tersebut.
  • Penerima Anda harus menerima permintaan HTTP POST pada URL HTTPS yang dapat diakses publik.
  • URL dapat berisi hingga 2.048 karakter dan tidak boleh menyertakan nama pengguna, kata sandi, atau fragmen URL seperti #section. Postoria tidak mengikuti pengalihan, jadi masukkan URL tujuan akhir.
  • Anda tidak memerlukan kunci Public API untuk menerima webhook. Penggunaan Public API, server MCP, atau integrasi n8n Postoria tetap memerlukan paket Pro atau Agency.

Mengatur webhook

  1. Buka Pengaturan, cari Webhook, lalu klik Konfigurasi.
  2. Masukkan alamat penerima Anda di URL webhook.
  3. Nyalakan Aktifkan webhook.
  4. Di bagian Peristiwa yang ingin diterima, pilih Penerbitan postingan berhasil, Penerbitan postingan gagal, atau keduanya. Setidaknya satu peristiwa harus dipilih saat webhook diaktifkan.
  5. Klik Simpan. Dialog ditutup, dan bagian Webhook menampilkan status Aktif beserta URL yang Anda simpan.
  6. Di bagian Webhook, cari Kunci penandatanganan. Nilainya disamarkan secara default. Gunakan tombol tampilkan atau salin untuk mendapatkan kunci tersebut dan mengatur verifikasi tanda tangan pada penerima Anda.

Jaga kerahasiaan kunci penandatanganan. Kunci ini memungkinkan penerima Anda memverifikasi bahwa permintaan ditandatangani oleh Postoria untuk profil Anda.

Setelah penerima siap, terbitkan postingan dan periksa Riwayat webhook untuk memastikan peristiwa sudah sampai. Mengaktifkan webhook tidak akan mengirimkan peristiwa untuk postingan yang penerbitannya telah selesai sebelumnya.

Memilih peristiwa yang dibutuhkan

Peristiwa menjelaskan percobaan penerbitan postingan yang telah selesai. Postoria menunggu seluruh publikasi yang dipilih selesai sebelum melaporkan hasil keseluruhannya.

PeristiwaPengaturanMakna
post.succeededPenerbitan postingan berhasilSemua publikasi yang dipilih berhasil diselesaikan.
post.failedPenerbitan postingan gagalPenerbitan selesai dengan kegagalan, termasuk ketika sebagian publikasi berhasil dan sebagian lainnya gagal.

Misalnya, jika postingan berhasil diterbitkan di satu akun tetapi gagal di akun lain, peristiwanya adalah post.failed. Periksa hasil setiap publikasi sebelum memutuskan mana yang akan dicoba lagi; publikasi yang berhasil sudah tayang.

Peristiwa ini mencakup percobaan penerbitan yang telah selesai. Peristiwa ini tidak melaporkan kesiapan media, pembaruan analitik, atau aktivitas kotak masuk. Permintaan penjadwalan yang ditolak atau kesalahan yang mencegah penerbitan dimulai tidak menghasilkan webhook hasil penerbitan. Tetap lakukan pemeriksaan terpisah untuk postingan yang tidak pernah mencapai hasil penerbitan akhir.

Membaca isi pesan

Postoria mengirimkan JSON dengan Content-Type: application/json; charset=utf-8. Contoh ini menunjukkan postingan dengan satu hasil yang berhasil dan satu hasil yang gagal:

{
  "id": "evt_7c7b19fd634441f3a0b460f2dc7e6812",
  "type": "post.failed",
  "occurred_at": "2026-11-15T12:00:00Z",
  "workspace_id": 42,
  "data": {
    "post_id": 1234,
    "results": [
      {
        "account_id": 101,
        "link_to_post": "https://example.com/published-post",
        "error": null
      },
      {
        "account_id": 102,
        "link_to_post": null,
        "error": "The social account needs to be reconnected."
      }
    ]
  }
}

ID, tautan, dan kesalahan di atas hanya merupakan contoh.

  • id mengidentifikasi peristiwa dan tetap sama pada setiap percobaan pengiriman.
  • type bernilai post.succeeded atau post.failed.
  • occurred_at adalah waktu UTC saat Postoria mencatat hasil penerbitan yang telah selesai, bukan waktu percobaan pengiriman terakhir.
  • workspace_id mengidentifikasi ruang kerja. Gunakan nilai ini untuk mengarahkan peristiwa jika penerima Anda melayani beberapa ruang kerja.
  • data.post_id adalah ID postingan di Postoria.
  • data.results berisi hasil publikasi dengan ID akun sosial, tautan postingan yang sudah terbit jika tersedia, serta kesalahan jika ada. Baik link_to_post maupun error dapat bernilai null.

Hasil ini menggunakan kolom yang sama dengan hasil postingan pada Public API. Satu akun dapat muncul lebih dari sekali, misalnya ketika sebuah postingan berisi beberapa Stories. Jangan mengasumsikan bahwa setiap akun selalu memiliki tepat satu hasil.

Memverifikasi tanda tangan

Setiap permintaan menyertakan tiga header:

HeaderNilai
webhook-idID peristiwa, sesuai dengan id pada isi pesan.
webhook-timestampWaktu Unix dalam detik untuk percobaan pengiriman ini.
webhook-signaturev1, diikuti tanda tangan HMAC-SHA256 yang dikodekan dalam Base64.

Untuk memverifikasi permintaan:

  1. Baca isi mentah permintaan sebelum mengurai JSON. Mengurai dan menyerialisasikannya kembali dapat mengubah byte dan membuat tanda tangan tidak valid.

  2. Hapus awalan whsec_ dari kunci penandatanganan Anda, lalu dekode nilai yang tersisa dari Base64 untuk mendapatkan byte kunci penandatanganan.

  3. Gabungkan header webhook-id, header webhook-timestamp, dan isi mentah permintaan dalam urutan tersebut, dengan karakter titik di antara setiap bagian:

    webhook-id.webhook-timestamp.raw-request-body
  4. Hitung HMAC-SHA256 dari byte UTF-8 string tersebut menggunakan kunci yang sudah didekode, lalu kodekan hasilnya dalam Base64.

  5. Bandingkan hasil Anda dengan nilai setelah v1, pada webhook-signature, menggunakan perbandingan dengan waktu eksekusi konstan.

  6. Periksa apakah stempel waktu yang ditandatangani masih berada dalam toleransi waktu yang diizinkan penerima Anda untuk membatasi pemutaran ulang permintaan lama. Gunakan stempel waktu pada header untuk pemeriksaan ini, karena percobaan ulang dapat tiba jauh setelah occurred_at.

Tolak permintaan dengan header tanda tangan yang hilang atau tidak valid sebelum memproses isinya. Gunakan webhook-id untuk mengenali peristiwa yang sudah diproses oleh penerima Anda.

Merespons dengan cepat dan menangani percobaan ulang

Kembalikan respons HTTP 2xx dalam 10 detik untuk mengonfirmasi penerimaan. Penerima yang praktis memverifikasi permintaan, menyimpan peristiwa beserta ID-nya secara persisten, lalu mengembalikan respons. Pekerjaan lanjutan yang lebih lama dapat dijalankan secara terpisah setelah konfirmasi tersebut.

Postoria mengantrekan pengiriman awal segera setelah hasil penerbitan dicatat. Respons selain 2xx, batas waktu yang terlampaui, dan kegagalan koneksi memicu percobaan ulang otomatis. Respons pengalihan juga dihitung sebagai percobaan pengiriman yang gagal.

Percobaan ulang dijadwalkan pada 5, 15, dan 30 menit, lalu 1, 3, 6, 12, dan 24 jam setelah percobaan pertama. Ini adalah selang waktu yang dihitung dari percobaan pertama, bukan jeda setelah percobaan sebelumnya. Pengiriman sebenarnya dapat berlangsung lebih lambat jika pemrosesan tertunda. Jadwal ini menyediakan hingga sembilan percobaan, termasuk percobaan awal.

ID peristiwa dan isi JSON tetap sama pada setiap percobaan ulang. Setiap percobaan mendapatkan stempel waktu pengiriman baru dan tanda tangan yang dihitung untuk percobaan tersebut. Pengiriman duplikat dapat terjadi, jadi pastikan penanganan berulang atas peristiwa yang sama tetap aman. Jangan mengandalkan urutan kedatangan peristiwa yang berbeda agar sesuai dengan urutan penerbitannya.

Mencoba ulang webhook hanya mengulangi pengiriman hasil. Tindakan ini tidak menerbitkan postingan lagi.

Memeriksa riwayat pengiriman

Buka Pengaturan → Webhook → Riwayat webhook, atau langsung buka Riwayat webhook.

Riwayat mencakup semua ruang kerja milik Anda dan disimpan selama 30 hari. Setiap baris menampilkan peristiwa, ID postingan, ID ruang kerja, status pengiriman, jumlah percobaan, dan status HTTP terakhir. Perluas baris untuk melihat ID pesan, waktu percobaan, waktu pengiriman berhasil, kesalahan jika ada, dan isi JSON.

Status pengirimanMakna
MenungguPesan menunggu pengiriman awal atau percobaan ulang.
MengirimPercobaan pengiriman sedang berlangsung.
TerkirimPenerima Anda mengembalikan respons HTTP yang menandakan keberhasilan.
GagalPercobaan pengiriman berakhir tanpa respons HTTP yang menandakan keberhasilan.

Status pengiriman dan hasil penerbitan adalah dua hal yang berbeda. Peristiwa post.failed dapat berstatus Terkirim: penerbitan mengalami kegagalan, tetapi penerima Anda berhasil menerima informasi tersebut.

Muat ulang halaman untuk melihat status pengiriman terbaru, dan gunakan Muat lebih banyak untuk melihat pesan yang lebih lama. Jika pemuatan gagal, Coba lagi akan mencoba memuat ulang riwayat. Tindakan ini tidak mengirim ulang webhook.

Mengubah URL atau menonaktifkan webhook

Di Pengaturan → Webhook, klik Konfigurasi, ubah URL atau matikan Aktifkan webhook, lalu klik Simpan. Perubahan berlaku untuk peristiwa yang baru dibuat.

Menutup dialog konfigurasi tanpa mengeklik Simpan akan membuang perubahan Anda.

Saat webhook dinonaktifkan, bagian Webhook menampilkan status Nonaktif dan menyembunyikan URL yang tersimpan serta kunci penandatanganan. Klik Konfigurasi untuk mengedit URL atau mengaktifkan webhook kembali.

Peristiwa yang sudah dicatat tetap menggunakan URL tujuan aslinya dan dapat terus dicoba kirim ulang. Menonaktifkan webhook tidak membatalkan pengiriman yang masih tertunda, dan mengubah URL tidak mengarahkannya ke alamat baru.

Mengatasi masalah

  • Pengaturan tidak dapat disimpan: pastikan URL menggunakan HTTPS, dapat diakses publik, tidak menyertakan kredensial atau fragmen, dan memenuhi batas panjang. Pilih setidaknya satu peristiwa saat mengaktifkan webhook.
  • Tidak ada peristiwa yang muncul: pastikan webhook sudah diaktifkan sebelum penerbitan selesai, peristiwa yang sesuai sudah dipilih, dan Anda adalah pemilik ruang kerja. Kesalahan sebelum penerbitan dimulai tidak termasuk dalam peristiwa ini.
  • Pengiriman terus gagal: periksa status HTTP terakhir dan kesalahan pada Riwayat webhook. Pastikan endpoint dapat diakses langsung, memiliki sertifikat HTTPS yang valid, menerima POST, dan mengembalikan 2xx dalam 10 detik.
  • Verifikasi tanda tangan gagal: gunakan isi mentah permintaan, dekode kunci dari Base64 setelah menghapus whsec_, dan sertakan nilai header serta titik pemisah yang persis sama dalam string yang ditandatangani.
  • Peristiwa yang sama tiba lagi: hilangkan duplikat berdasarkan ID peristiwa, bukan ID postingan. Percobaan penerbitan berikutnya untuk postingan yang sama dapat menghasilkan peristiwa yang berbeda.