Apa Itu Webhook? Cara Aplikasi Saling Memberitahu

Webhook ialah mesej automatik yang dihantar satu perkhidmatan kepada aplikasi anda sebaik sahaja sesuatu berlaku. Apabila pembayaran pelanggan berjaya, Stripe menghantar webhook ke alamat dalam aplikasi anda yang menyatakan “pembayaran berjaya, ini butirannya”, dan aplikasi anda bertindak balas — menandakan pesanan sebagai dibayar, menghantar resit, membuka akaun. Ringkasnya: API ialah aplikasi anda bertanya soalan kepada perkhidmatan lain; webhook ialah perkhidmatan lain memanggil aplikasi anda untuk memberitahu sesuatu.

Mengapa ia penting apabila anda membina dengan AI

Sebaik sahaja aplikasi anda menerima pembayaran, menerima penghantaran borang daripada alat lain, atau menyambung kepada perkhidmatan seperti GitHub, Shopify atau kalendar, anda akan bertemu webhook. Ia biasanya cara yang betul untuk tahu sesuatu telah berlaku — tetapi di sinilah aplikasi yang dibina dengan AI paling kerap tersilap secara halus:

• Titik akhir menerima sebarang permintaan, jadi sesiapa sahaja boleh memalsukan peristiwa “pembayaran berjaya”.
• Aplikasi memberikan akses pada halaman pengalihan daftar keluar, bukan pada webhook, jadi orang yang menutup tab awal tidak pernah mendapat apa yang mereka bayar, dan orang yang menemui URL kejayaan mendapatkannya secara percuma.
• Peristiwa yang sama tiba dua kali dan pelanggan mendapat dua pesanan atau dua e-mel.

Memahami cara webhook berfungsi membolehkan anda meminta perlindungan ini dari awal.

Analogi harian: mesej penghantaran

Anda boleh tahu sama ada bungkusan anda telah sampai dengan dua cara. Anda boleh berjalan ke pintu hadapan setiap sepuluh minit untuk memeriksa (itulah polling — aplikasi anda berulang kali memanggil API untuk bertanya “ada apa-apa baharu?”). Atau kurier boleh menghantar mesej teks apabila bungkusan telah dihantar (itulah webhook).

Mesej teks jelas lebih baik — selagi anda boleh mempercayainya. Jika sesiapa sahaja boleh menghantar mesej “bungkusan dihantar” kepada anda, anda mahu cara untuk tahu ia benar-benar datang daripada kurier. Dan jika telefon anda mati ketika mesej itu tiba, anda mahu kurier mencuba semula kemudian. Dua perkara itu — pengesahan dan cubaan semula — ialah kebanyakan yang menjadikan webhook rumit.

Cara webhook berfungsi, langkah demi langkah

1. Anda mencipta titik akhir dalam bahagian belakang aplikasi anda: URL seperti https://aplikasianda.com/webhooks/stripe yang menerima permintaan POST.
2. Anda mendaftarkan URL itu dengan pembekal dan memilih peristiwa yang anda mahu (contohnya “checkout selesai” dan “langganan dibatalkan”).
3. Pembekal memberikan rahsia penandatanganan. Anda menyimpannya sebagai rahsia di pelayan anda — lihat pembolehubah persekitaran dan rahsia.
4. Satu peristiwa berlaku. Pembekal menghantar permintaan HTTP ke URL anda dengan badan JSON yang menerangkannya, serta pengepala tandatangan.
5. Aplikasi anda mengesahkan tandatangan, merekodkan ID peristiwa, membalas dengan kod kejayaan (200) dengan cepat, dan kemudian melakukan kerjanya.
6. Jika aplikasi anda tidak membalas dengan kejayaan, banyak pembekal akan mencuba semula kemudian.

Tandatangan

Tandatangan membuktikan permintaan itu datang daripada pembekal dan tidak diubah. Stripe, sebagai contoh, mengira HMAC (sejenis cap jari berkunci) dengan SHA-256 ke atas badan permintaan dan cap masa, menggunakan rahsia penandatanganan, dan menghantarnya dalam pengepala Stripe-Signature. Aplikasi anda membuat pengiraan yang sama dengan salinan rahsianya; jika keputusannya sepadan, permintaan itu tulen. Oleh kerana cap masa juga ditandatangani, anda boleh menolak permintaan lama yang direkodkan seseorang dan dimainkan semula kemudian — pustaka Stripe mempunyai toleransi lalai lima minit, mengikut dokumentasinya setakat September 2026.

Satu perincian praktikal: tandatangan dikira ke atas badan permintaan mentah. Jika rangka kerja anda menghuraikan dan memformat semula JSON sebelum anda mengesahkannya, semakan itu gagal. Ini pepijat yang sangat biasa.

Cubaan semula, pendua dan susunan

Pembekal berbeza, jadi semak dokumentasi setiap satu. Setakat September 2026:

Dokumentasi Stripe juga menyatakan bahawa peristiwa tidak dijamin tiba mengikut susunan ia berlaku, dan peristiwa yang sama kadangkala boleh tiba lebih daripada sekali, jadi ia mengesyorkan supaya ID peristiwa dijejaki.

Pelajaran umum berlaku untuk mana-mana pembekal: peristiwa boleh tiba lewat, lebih daripada sekali dan tidak mengikut susunan. Pengendali anda sepatutnya idempoten — memproses peristiwa yang sama dua kali memberi kesan yang sama seperti memprosesnya sekali.

Contoh kerja: membuka kursus berbayar

Anda menjual kursus dalam talian. Pelajar mengklik Beli, membayar di halaman checkout yang dihoskan Stripe, dan dihantar kembali ke laman anda.

Cara yang rapuh: halaman “terima kasih” membuka kursus itu. Jika pelajar menutup pelayar semasa pengalihan, mereka sudah membayar tetapi tiada akses. Jika seseorang meneka URL halaman terima kasih itu, mereka mendapat akses tanpa membayar.

Cara webhook:

1. Apabila Stripe mengesahkan pembayaran, ia menghantar peristiwa checkout.session.completed ke /webhooks/stripe.
2. Bahagian belakang anda mengesahkan tandatangan dengan rahsia penandatanganan. Jika gagal, ia membalas 400 dan tidak melakukan apa-apa.
3. Ia menyemak sama ada ID peristiwa itu sudah diproses. Jika ya, ia membalas 200 dan berhenti.
4. Ia menyimpan ID peristiwa, membalas 200, dan kemudian memberikan akses kepada pelajar dan menghantar e-mel alu-aluan.
5. Halaman terima kasih hanya memaparkan “Pembayaran diterima — kursus anda akan muncul sebentar lagi” dan menyemak status akses pelajar.

Kemudian, jika langganan dibatalkan atau kad gagal, peristiwa webhook lain memberitahu aplikasi anda untuk mengalih keluar atau menggantung akses. Begitulah produk langganan kekal selari dengan pengebilan — lihat apa itu SaaS dan cara menambah pembayaran ke aplikasi anda.

Istilah utama

• Titik akhir (endpoint): URL dalam aplikasi anda yang menerima webhook.
• Peristiwa / muatan (payload): apa yang berlaku, dan data yang menerangkannya (biasanya JSON).
• Rahsia penandatanganan (signing secret): rahsia kongsi yang digunakan untuk mengesahkan tandatangan.
• Idempoten (idempotent): selamat dijalankan lebih daripada sekali dengan hasil yang sama.
• Polling: berulang kali bertanya API untuk perubahan dan bukannya menunggu webhook.
• Terowong (tunnel): alat yang memberi komputer riba URL awam sementara supaya webhook boleh sampai kepadanya semasa pembangunan.

Kesilapan dan salah faham biasa

• Tidak mengesahkan tandatangan. URL titik akhir bukan rahsia. Pengesahanlah yang menjadikan permintaan itu boleh dipercayai.
• Melakukan kerja yang perlahan sebelum membalas. Menghantar e-mel atau menjana PDF sebelum memberi respons boleh menyebabkan tamat masa, yang mencetuskan cubaan semula, yang menyebabkan pendua.
• Menganggap tepat sekali, mengikut susunan. Rekod ID peristiwa dan jangan bergantung pada susunan ketibaan.
• Menggunakan URL pratonton. Webhook memerlukan alamat awam yang stabil. Pratonton peribadi dan localhost tidak boleh dicapai dari internet; gunakan URL yang diterbitkan anda (atau terowong semasa menguji).
• Mencampurkan rahsia ujian dan langsung. Pembekal selalunya mengeluarkan rahsia penandatanganan yang berbeza untuk mod ujian dan mod langsung. Simpan kedua-duanya dan gunakan yang betul.
• Mempercayai muatan secara membuta tuli untuk keputusan penting. Untuk tindakan berisiko tinggi, adalah munasabah untuk mendapatkan keadaan terkini daripada API pembekal selepas menerima peristiwa itu.

Apa yang patut diminta daripada pembina AI anda

Tambah titik akhir POST /webhooks/stripe di pelayan. Sahkan tandatangan Stripe menggunakan badan permintaan mentah dan rahsia STRIPE_WEBHOOK_SECRET. Tolak tandatangan tidak sah dengan 400. Simpan setiap ID peristiwa dan langkau peristiwa yang sudah diproses. Balas 200 dengan cepat, kemudian kendalikan checkout.session.completed dengan menandakan pesanan sebagai dibayar dan menghantar resit. Log jenis peristiwa. Jangan beri akses daripada halaman kejayaan checkout.

Kemudian uji: hantar peristiwa ujian dari papan pemuka pembekal, hantar peristiwa yang sama sekali lagi, dan hantar permintaan dengan tandatangan yang salah. Hanya yang pertama patut mengubah apa-apa.

Webhook dalam Mythex

Mythex tidak menjalankan perkhidmatan webhook berasingan; anda meminta ejen menambah titik akhir webhook dalam bahagian belakang aplikasi anda sendiri, dan menunjuk pembekal ke URL yang diterbitkan anda, kerana webhook memerlukan alamat awam. Rahsia penandatanganan dimasukkan ke dalam rahsia projek anda, dan jika anda menukarnya pada aplikasi langsung, anda perlu menerbitkan semula. Resipi dokumentasi tentang mengendalikan webhook mempunyai prompt permulaan, dan templat kedai ialah titik permulaan yang baik untuk aplikasi yang menerima pembayaran.

Soalan lazim