Memahami Struktur Permintaan Webhook
Webhook ialah mekanisme komunikasi automatik yang menghantar data dari satu sistem ke sistem lain apabila sesuatu peristiwa berlaku. Untuk memahami struktur data yang dihantar, pembangun API, jurutera integrasi, wakil khidmat pelanggan, dan penyelenggara automasi perlu memeriksa komponen utama permintaan tersebut. Komponen ini merangkumi kaedah HTTP (seperti POST, PUT, PATCH, GET, atau DELETE), pengepala (headers), dan badan permintaan (body).
Pemeriksaan struktur ini sangat penting untuk memastikan sistem penerima dapat memproses data dengan betul. Format badan permintaan biasanya dihantar dalam bentuk JSON atau data borang yang dikodkan URL (URL-encoded form data). Dengan memeriksa struktur mentah sebelum sebarang penghuraian sebelah pelayan berlaku, anda boleh mengenal pasti ralat sintaksis atau ketidakpadanan jenis data yang sering menyebabkan kegagalan integrasi.
Peranan Pengepala dalam Komunikasi Webhook
Pengepala HTTP membawa metadata penting tentang permintaan webhook. Pengepala ini menyatakan jenis kandungan yang dihantar, maklumat pelayan pengirim, serta maklumat keselamatan. Dalam komunikasi webhook, pengepala sering digunakan untuk menghantar cap masa (timestamp) dan tandatangan kriptografi (signature).
Alat ini membolehkan anda memasukkan pengepala dengan format satu pengepala setiap baris menggunakan format "Nama: nilai". Walau bagaimanapun, terdapat beberapa had teknikal yang perlu dipatuhi semasa melakukan pemeriksaan:
- Maksimum 200 baris pengepala yang tidak kosong.
- Panjang keseluruhan pengepala tidak boleh melebihi 100,000 aksara.
Jika had ini dilanggar atau format yang dimasukkan salah, sistem akan memaparkan mesej ralat khusus seperti:
- "Terdapat terlalu banyak baris pengepala. Pastikan permintaan kepada 200 pengepala atau kurang."
- "Pengepala terlalu panjang untuk alat ini. Alih keluar nilai yang tidak berkaitan atau berulang."
- "
‹line›: Baris pengepala tidak sah. Gunakan Nama: nilai."
Format Badan Webhook dan Kepentingan Kandungan Mentah
Badan permintaan webhook mengandungi muatan (payload) data sebenar yang dihantar oleh sistem sumber. Untuk memeriksa kandungan ini dengan tepat, anda perlu menggunakan badan mentah tepat yang ditangkap sebelum sebarang penghuraian sebelah pelayan dilakukan. Sebarang perubahan pada ruang kosong (whitespace) atau susunan medan boleh menjejaskan hasil analisis.
Alat ini menyokong pemeriksaan badan permintaan sehingga maksimum 1,000,000 aksara. Jika had ini dilampaui, ralat "Badan terlalu panjang untuk alat ini. Simpan di bawah 1,000,000 aksara." akan dipaparkan.
Sistem mengendalikan format badan berdasarkan jenis dikesan:
- JSON: Diproses menggunakan
JSON.parse. Proses ini akan menyusun semula medan, yang bermaksud susunan asal dan ruang kosong asal akan hilang. Jika proses penghuraian gagal, ralat "Badan kelihatan seperti JSON tetapi tidak dapat dihuraikan." akan muncul. - URL-encoded: Data borang akan dikesan dan diformatkan. Jika terdapat ralat pengekodan, ralat "Badan borang mengandungi peratus pelarian yang tidak lengkap." akan dipaparkan.
- Format Lain: Jenis badan selain JSON dan URL-encoded akan dipaparkan sebagai teks biasa tanpa sebarang pemformatan. Jika tiada data dimasukkan, output akan memaparkan "(badan kosong)".
Konsep Tandatangan dan Cap Masa Webhook
Banyak penyedia webhook menghantar pengepala khas yang mengandungi tandatangan kriptografi dan cap masa untuk membolehkan sistem penerima mengesahkan bahawa permintaan itu benar-benar datang daripada sumber yang dipercayai. Alat ini secara automatik mengesan corak nama pengepala biasa yang berkaitan dengan keselamatan, seperti signature, hmac, digest, serta nama cap masa yang biasa digunakan.
Jika tiada pengepala yang sepadan ditemui, output akan memaparkan "Tiada tandatangan biasa atau pengepala cap waktu webhook ditemui.".
Perbezaan Antara Memeriksa dan Mengesahkan Ketulenan
Satu perkara penting yang perlu difahami ialah perbezaan antara mengesan medan tandatangan dan mengesahkan ketulenan webhook. Menemui medan tandatangan tidak membuktikan bahawa permintaan itu sahih — pengesahan sebenar memerlukan peraturan menandatangani pengirim, rahsia atau kunci, dan bait permintaan asal.
Alat ini tidak melakukan pengiraan HMAC, tidak menjalankan algoritma kriptografi, tidak memeriksa bait asal muatan, tidak menyimpan rahsia, tidak mengira tetingkap ulangan (replay window), dan tidak melakukan pengesahan khusus penyedia. Ia hanya berfungsi untuk mengenal pasti kehadiran pengepala tersebut dalam permintaan yang anda tampal.
Pengenalan kepada cURL untuk Ujian Tempatan
Selepas memeriksa struktur webhook, langkah seterusnya dalam pembangunan adalah menguji bagaimana aplikasi tempatan anda mengendalikan permintaan tersebut. Alat ini membantu proses ini dengan menghasilkan arahan cURL yang dipetik secara shell (shell-quoted) secara automatik.
Arahan cURL yang dijana ditetapkan secara khusus untuk menyasarkan URL ujian tempatan berikut:
http://localhost:3000/webhooks
Dengan menyalin arahan cURL ini, anda boleh menghantar semula permintaan webhook yang sama dari terminal komputer anda ke pelayan pembangunan tempatan tanpa perlu mencetuskan peristiwa sebenar daripada penyedia webhook luar.
Pemprosesan Data dan Privasi
Apabila mengendalikan data webhook yang mungkin mengandungi maklumat sensitif, privasi data adalah keutamaan. Proses pemeriksaan dan analisis data ini dilakukan sepenuhnya di dalam pelayar web anda. Permintaan yang ditampal anda kekal dalam penyemak imbas anda. BroBroGo tidak memuat naik atau menyimpannya.
Soalan Lazim (FAQ)
Bolehkah halaman ini menerima panggilan balik webhook secara langsung? Tidak. Tampal permintaan yang ditangkap di sini untuk pemeriksaan. Halaman tidak membuat titik akhir awam, menerima panggilan balik atau menghantar permintaan ujian yang dijana.
Format badan webhook yang manakah boleh saya periksa? JSON dan badan borang yang dikodkan URL dikesan dan diformatkan. Badan lain kekal sebagai teks biasa supaya alat itu tidak meneka kandungan XML, berbilang bahagian atau binari.
Adakah mencari medan tandatangan membuktikan permintaan itu sahih? Tidak. Alat ini hanya memaparkan tandatangan dan pengepala cap masa yang berkaitan. Pengesahan sebenar memerlukan peraturan tandatangan tepat penghantar, kunci rahsia atau awam dan bait permintaan asal.