Indonesian (Bahasa Indonesia) translation by ⚡ Rova Rindrata (you can also view the original English article)
Webhook adalah callback HTTP yang terjadi saat terjadi sesuatu; sebuah sistem pemberitahuan kejadian sederhana melalui HTTP POST yang memungkinkan pengembang untuk dengan mudah mengakses pemberitahuan aktivitas pembayaran, seperti pembaruan status pembayaran, atau biaya berulang. Anda bisa melakukan tindakan di back-end setelah memproses setiap notifikasi, seperti:
- Mengirim email konfirmasi pembelian ke pelanggan Anda.
- Mengaktifkan pengunduhan media digital.
- Menerbitkan pengembalian dana.
- Melacak langganan yang aktif.
Untuk membuat Webhook, navigasikan ke Dashboard PayPal, dan klik My Apps & Credentials. Kemudian pilih aplikasi yang ingin Anda setel pada Webhooks.
Pengembang PayPalAnda dapat melihat rincian tentang aplikasi Anda. Perhatikan di kanan atas bahwa ada dua tombol (Sandbox, Live), saya akan menggunakan Sandbox selama tutorial ini, tapi Anda perlu mengatur pengaturan Live Anda sebelum pergi Live. Untuk mengkonfigurasi Webhooks untuk aplikasi ini, klik Add Webhook seperti yang ditampilkan di tangkapan layar:
Pilih Event Types yang Anda minati untuk mendapatkan notifikasi, dan masukkan URL tempat Webhooks akan dikirimkan (itu harus HTTPS). Untuk menangani panggilan Webhook, saya akan menambahkan metode tindakan baru ke HomeController yang disebut 'Webhook':
1 |
public IActionResult Webhook() |
2 |
{
|
3 |
// TODO: Handle Webhook call |
4 |
} |
Jadi Url Webhook dalam kasus ini adalah: https://pedroalonso.localtunnel.me/home/webhook. Saya akan menjelaskan bagian 'localtunnel' di bagian berikutnya.
Dashboard Pengembang PayPalSaat Anda menyimpan Webhook, Anda akan melihat layar konfirmasi ini:
Webhook Berhasil DibuatSekarang setelah Webhook disiapkan, Anda dapat melihat di menu kiri di bawah 'Webhooks Simulator', di sini Anda dapat mengirim kejadian webhook 'test' ke URL Anda untuk menguji kode Anda bekerja. Juga, di bawah 'Webhooks Events' Anda dapat melihat semua kejadian yang dikirim PayPal untuk aplikasi ini. Anda dapat memverifikasi bahwa Anda menangani kejadian dengan benar dan mengirimnya kembali jika Anda ingin melakukan pengujian lebih lanjut.
Untuk melihat bagaimana kerja Webhooks, saya menjalankan proyek yang kami bangun di tutorial sebelumnya, dan saya membuat 'otorisasi pembayaran dan penangkapan kemudian', sehingga PayPal akan mengirimkan kejadian tersebut. Setelah menjalankan sampel, saya mengklik 'Webhooks Event' dan saya dapat melihat bahwa kejadian telah dikirim:
Kejadian WebHookSeperti yang bisa Anda lihat, di sebelah kanan ada tombol Resend jika Anda ingin men-debug kode Anda dan melihat bagaimana menerapkan handler dengan benar. Selain itu, jika Anda mengeklik kejadian tersebut, Anda dapat melihat semua detailnya:
Rincian Kejadian WebHookIni adalah JSON penuh untuk Webhook Event:
1 |
{
|
2 |
"id": "WH-9U51749144910293K-8LX80763BC1567402", |
3 |
"create_time": "2016-01-19T17:50:30Z", |
4 |
"resource_type": "sale", |
5 |
"event_type": "PAYMENT.SALE.COMPLETED", |
6 |
"summary": "Payment completed for $ 100.0 USD", |
7 |
"resource": { |
8 |
"amount": { |
9 |
"total": "100.00", |
10 |
"currency": "USD", |
11 |
"details": { |
12 |
"subtotal": "100.00", |
13 |
"tax": "15.00", |
14 |
"shipping": "10.00" |
15 |
}
|
16 |
},
|
17 |
"id": "73G8209522783053E", |
18 |
"parent_payment": "PAY-7MB27930V5981832YK2PHN7Q", |
19 |
"update_time": "2016-01-19T17:49:05Z", |
20 |
"create_time": "2016-01-19T17:49:05Z", |
21 |
"payment_mode": "INSTANT_TRANSFER", |
22 |
"state": "completed", |
23 |
"links": [ |
24 |
{
|
25 |
"href": "https://api.sandbox.paypal.com/v1/payments/sale/73G8209522783053E", |
26 |
"rel": "self", |
27 |
"method": "GET" |
28 |
},
|
29 |
{
|
30 |
"href": "https://api.sandbox.paypal.com/v1/payments/sale/73G8209522783053E/refund", |
31 |
"rel": "refund", |
32 |
"method": "POST" |
33 |
},
|
34 |
{
|
35 |
"href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-7MB27930V5981832YK2PHN7Q", |
36 |
"rel": "parent_payment", |
37 |
"method": "GET" |
38 |
}
|
39 |
],
|
40 |
"protection_eligibility_type": "ITEM_NOT_RECEIVED_ELIGIBLE,UNAUTHORIZED_PAYMENT_ELIGIBLE", |
41 |
"transaction_fee": { |
42 |
"value": "3.20", |
43 |
"currency": "USD" |
44 |
},
|
45 |
"protection_eligibility": "ELIGIBLE" |
46 |
},
|
47 |
"status": "PENDING", |
48 |
"transmissions": [ |
49 |
{
|
50 |
"webhook_url": "https://pedroalonso.localtunnel.me/home/webhook", |
51 |
"response_headers": { |
52 |
"Date": "Wed, 20 Jan 2016 12:53:51 GMT", |
53 |
"Content-Length": "53", |
54 |
"HTTP/1.1 502 Bad Gateway": "", |
55 |
"SERVER_INFO": "", |
56 |
"Connection": "keep-alive", |
57 |
"Server": "nginx/1.7.8" |
58 |
},
|
59 |
"transmission_id": "218dc9c0-bed5-11e5-927f-6b62a8a99ac4", |
60 |
"status": "PENDING", |
61 |
"timestamp": "2016-01-19T17:50:30Z" |
62 |
}
|
63 |
],
|
64 |
"links": [ |
65 |
{
|
66 |
"href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9U51749144910293K-8LX80763BC1567402", |
67 |
"rel": "self", |
68 |
"method": "GET", |
69 |
"encType": "application/json" |
70 |
},
|
71 |
{
|
72 |
"href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9U51749144910293K-8LX80763BC1567402/resend", |
73 |
"rel": "resend", |
74 |
"method": "POST", |
75 |
"encType": "application/json" |
76 |
}
|
77 |
]
|
78 |
}
|
Seperti yang dapat Anda lihat di gambar, detail kejadian dikodekan dalam JSON dan mereka dikirim sebagai body permintaan ke handler URL Webhook Anda. Juga, ada beberapa properti penting yang perlu kita gunakan di handler kita:
- id: Ini adalah id dari kejadian webhook, dan kita perlu mengirimkan parameter ini ke PayPal jika kita ingin mengambil kejadian webhook yang spesifik.
- event_type: Ini digunakan untuk mengetahui jenis kejadian yang kita terima karena kita mungkin perlu mengolah berbagai jenis kejadian dengan berbagai cara.
- resource.parent_payment: Ini adalah id dari pembayaran yang berkaitan dengan kejadian ini. Kita mungkin menyimpan id ini dalam database, dan bisa mengirim email ke pelanggan kita atau mengirimkan barang yang dibeli oleh pelanggan.
Berdasarkan penjelasan sebelumnya, inilah kode tindakan controller untuk mengolah Webhook:
1 |
public IActionResult Webhook() |
2 |
{
|
3 |
// The APIContext object can contain an optional override for the trusted certificate.
|
4 |
var apiContext = PayPalConfiguration.GetAPIContext(); |
5 |
|
6 |
// Get the received request's headers
|
7 |
var requestheaders = HttpContext.Request.Headers; |
8 |
|
9 |
// Get the received request's body
|
10 |
var requestBody = string.Empty; |
11 |
using (var reader = new System.IO.StreamReader(HttpContext.Request.Body)) |
12 |
{
|
13 |
requestBody = reader.ReadToEnd(); |
14 |
}
|
15 |
|
16 |
dynamic jsonBody = JObject.Parse(requestBody); |
17 |
string webhookId = jsonBody.id; |
18 |
var ev = WebhookEvent.Get(apiContext, webhookId); |
19 |
|
20 |
// We have all the information the SDK needs, so perform the validation.
|
21 |
// Note: at least on Sandbox environment this returns false.
|
22 |
// var isValid = WebhookEvent.ValidateReceivedEvent(apiContext, ToNameValueCollection(requestheaders), requestBody, webhookId);
|
23 |
|
24 |
switch (ev.event_type) |
25 |
{
|
26 |
case "PAYMENT.CAPTURE.COMPLETED": |
27 |
// Handle payment completed
|
28 |
break; |
29 |
case "PAYMENT.CAPTURE.DENIED": |
30 |
// Handle payment denied
|
31 |
break; |
32 |
// Handle other webhooks
|
33 |
default: |
34 |
break; |
35 |
}
|
36 |
|
37 |
return new HttpStatusCodeResult(200); |
38 |
}
|
Beberapa hal yang perlu dijelaskan dari fungsi sebelumnya. Dari baris 10-16, saya hanya membaca body dari permintaan dan menguraikan objek JSON ke objek C# yang dinamis. Pada baris 18, yang bersifat opsional, saya menghubungi API PayPal dengan Id kejadian untuk mendapatkan detail kejadian lengkap. Hal ini dilakukan untuk keamanan untuk memverifikasi bahwa saya menggunakan objek PayPal yang valid. On line 24 Saya telah membuat sebuah tombol untuk mengevaluasi jenis Webhooks yang ingin saya proses dan menuliskan kode kustom sesuai kebutuhan.
Seperti yang juga bisa Anda lihat, baris 22 dikomentari. Rupanya metode tersebut memvalidasi bahwa sertifikat SSL dari Request adalah valid dan milik PayPal, namun tidak sesuai dengan mode Sandbox. Ini mungkin berhasil di Live, tapi saya tidak suka memiliki kode Live yang tidak diuji, terutama jika menangani Gateway Pembayaran, jadi saya memilih untuk menghapusnya dan menggunakan pendekatan yang berbeda. Jika Anda menggunakan versi PHP dari perpustakaan SDK PayPal, ingatlah bahwa fungsi 'ValidateReceivedEvent' tidak ada.
Pengujian Webhooks: Tunnel yang Aman
Seperti yang telah Anda lihat sebelumnya, untuk menguji Webhook, kita perlu mengonfigurasi URL publik yang dapat digunakan PayPal untuk mengirim kejadian. Jika kita bekerja secara lokal, biasanya kita kembangkan dengan menggunakan 'localhost', jadi itu akan menjadi masalah kecil. Untuk mengatasinya, kita perlu mengkonfigurasi tunnel yang aman ke komputer lokal kita.
Localtunnel adalah perangkat lunak kecil yang menciptakan tunnel yang aman antara mesin lokal Anda dan domain yang dapat diakses publik. Ini berguna untuk pengujian Webhook, namun Anda juga dapat menggunakannya untuk berbagi URL nyata ke aplikasi web yang berjalan di mesin pengembangan Anda untuk tujuan pengujian, umpan balik, atau tugas lainnya.
Anda harus memiliki Node.js untuk dapat menginstal localtunnel. Lalu cukup buka konsol atau terminal, dan jalankan:
$ npm install -g localtunnel
Untuk membuat tunnel, jalankan:
$ lt --port 5000 --subdomain pedroalonso
Itu akan memetakan URL 'https://pedroalonso.localtunnel.me' ke 'localhost: 5000'. Jika Anda menjalankan proyek Anda di IIS Express, Anda mungkin akan menggunakan port yang berbeda, jadi Anda harus memikirkannya dalam perintah Anda.
Setelah localtunnel disiapkan dan proyek kita berjalan, saya telah menambahkan sebuah breakpoint di Visual Studio untuk mengevaluasi data yang saya dapatkan. Seperti yang dapat Anda lihat di tangkapan layar ini, saya telah memetakan objek kejadian JSON ke objek dinamis C#.
Mengambil kejadian dari API PayPal menggunakan Id kejadian, kita juga mendapatkan detail kejadian, seperti yang dapat Anda lihat di sini:
Kesimpulan
Webhooks menjadi cara standar untuk REST API untuk memberi tahu aplikasi tentang kejadian-kejadian. Seperti yang Anda lihat, mereka cukup mudah ditangani, dan mereka digunakan oleh banyak perusahaan seperti Stripe, SendGrid, MailChimp, dll. PayPal dulu memiliki Instant Payment Notification, dan ini masih digunakan, namun mereka menyarankan untuk menerapkan Webhooks bila memungkinkan.
Saya pikir akan sangat menarik jika lebih banyak aplikasi konsumen yang ditawarkan Webhooks juga. Kemampuan untuk memulai sebuah proses berdasarkan sebuah kejadian dalam aplikasi terpisah sangat berguna dan menawarkan sekilas pada masa depan web real-time.
