Menyiapkan notifikasi menggunakan webhook

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

Apa itu webhook?

Webhook menentukan pengendali callback HTTP yang dipicu oleh peristiwa. Anda dapat membuat webhook dan mengonfigurasinya untuk menangani notifikasi peristiwa, sebagai alternatif untuk menggunakan template notifikasi monetisasi, seperti yang dijelaskan dalam Menyiapkan notifikasi menggunakan template notifikasi.

Untuk menyiapkan notifikasi menggunakan webhook, selesaikan langkah-langkah berikut menggunakan UI Pengelolaan Tepi, atau Pengelolaan dan Monetisasi API:

  1. Tambahkan webhook yang menentukan pengendali callback untuk peristiwa notifikasi menggunakan UI atau API.
  2. Siapkan pengendali callback.
  3. Siapkan notifikasi untuk paket tarif yang dapat disesuaikan menggunakan UI atau API.

Mengelola webhook

Tambahkan dan kelola webhook yang menentukan pengendali callback untuk peristiwa notifikasi menggunakan UI atau API.

Mengelola webhook menggunakan UI

Tambahkan dan kelola webhook yang menentukan pengendali callback untuk peristiwa notifikasi menggunakan UI, seperti yang dijelaskan di bagian berikut.

Menjelajahi halaman Webhook

Akses halaman Webhook, seperti yang dijelaskan di bawah ini.

Edge

Untuk mengakses halaman Webhook menggunakan UI Edge:

  1. Login ke apigee.com/edge.
  2. Pilih Publikasi > Monetisasi > Webhook di menu navigasi sebelah kiri.

Halaman Webhook ditampilkan.

Seperti yang ditandai dalam gambar, halaman Webhook memungkinkan Anda untuk:

Edge Klasik (Private Cloud)

Untuk mengakses halaman Webhook menggunakan UI Edge Klasik:

  1. Login ke http://ms-ip:9000, dengan ms-ip adalah alamat IP atau nama DNS node Server Pengelolaan.

  2. Pilih Admin > Webhooks.

Halaman Webhook akan ditampilkan.

Halaman Webhook memungkinkan Anda untuk:

Menambahkan webhook menggunakan UI

Untuk menambahkan webhook menggunakan UI:

  1. Akses halaman Webhooks.
  2. Klik + Webhook.
  3. Masukkan informasi berikut (semua kolom wajib diisi).
    Kolom Deskripsi
    Nama Nama webhook.
    URL URL pengendali callback yang akan dipanggil saat notifikasi peristiwa dipicu. Lihat Menyiapkan handler callback.
  4. Klik Simpan.

Webhook ditambahkan ke daftar dan diaktifkan secara default.

Mengedit webhook menggunakan UI

Untuk mengedit webhook menggunakan UI:

  1. Akses halaman Webhooks.
  2. Arahkan kursor ke webhook yang ingin diedit, lalu klik di menu tindakan.
  3. Edit kolom webhook, sesuai kebutuhan.
  4. Klik Perbarui Webhook.

Mengaktifkan atau menonaktifkan webhook menggunakan UI

Untuk mengaktifkan atau menonaktifkan webhook menggunakan UI:

  1. Akses halaman Webhook.
  2. Arahkan kursor ke webhook dan alihkan tombol status untuk mengaktifkan atau menonaktifkannya.

Menghapus webhook menggunakan UI

Untuk menghapus webhook menggunakan UI:

  1. Akses halaman Webhooks.
  2. Arahkan kursor ke webhook yang ingin dihapus, lalu klik .

Webhook akan dihapus dan dihapus dari daftar.

Mengelola webhook menggunakan API

Tambahkan dan kelola webhook menggunakan API seperti yang dijelaskan di bagian berikut.

Melihat semua webhook menggunakan API

Lihat semua webhook dengan mengeluarkan permintaan GET ke /mint/organizations/{org_name}/webhooks. Contoh:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks" \
  -H "Content-Type: application/json " \
  -u email:password

Berikut ini contoh respons yang ditampilkan:

{
  "totalRecords": 2,
  "webhooks": [
    {
      "created": 1460162656342,
      "enabled": false,
      "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
      "name": "webhook1",
      "postUrl": "http://mycompany.com/callbackhandler1",
      "updated": 1460162656342,
      "updatedBy": "joe@example.com"
    },
        {
      "created": 1460138724352,
      "createdBy": "joe@example.com",
      "enabled": true,
      "id": "a39ca777-1861-49cf-a397-c9e92ab3c09f",
      "name": "webhook2",
      "postUrl": "http://mycompany.com/callbackhandler2",
      "updated": 1460138724352,
      "updatedBy": "joe@example.com"
    }

  ]
}

Melihat webhook menggunakan API

Lihat satu webhook dengan mengeluarkan permintaan GET ke /mint/organizations/{org_name}/webhooks/{webhook_id}.

Contoh:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

Berikut adalah contoh respons:

{
   "created": 1460162656342,
   "enabled": false,
   "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
   "name": "webhook1",
   "postUrl": "http://mycompany.com/callbackhandler1",
   "updated": 1460162656342,
   "updatedBy": "joe@example.com"
 }

Menambahkan webhook menggunakan API

Tambahkan webhook dengan mengeluarkan permintaan POST ke /mint/organizations/{org_name}/webhooks. Anda harus meneruskan nama webhook dan URL pengendali callback yang akan dipanggil saat notifikasi peristiwa dipicu.

Misalnya, kode berikut akan membuat webhook bernama webhook3 dan menetapkan callbackhandler3 ke webhook:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks"
  -H "Content-Type: application/json "
  -d '{
    "name": "webhook3",
    "postURL": "http://mycompany.com/callbackhandler3"
    }' \
    -u email:password

Berikut adalah contoh respons:

{
  "created": 1460385534555,
  "createdBy": "joe@example.com",
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler3",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Mengedit webhook menggunakan API

Edit webhook dengan mengeluarkan permintaan PUT ke /mint/organizations/{org_name}/webhooks/{webhook_id}. Teruskan pembaruan dalam isi permintaan.

Misalnya, kode berikut akan memperbarui pengendali callback yang terkait dengan webhook1:

curl -X PUT "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "postURL": "http://mycompany.com/callbackhandler4"
  }' \
  -u email:password

Berikut ini contoh responsnya:

{
  "created": 1460385534555,
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Mengaktifkan atau menonaktifkan webhook menggunakan API

Aktifkan atau nonaktifkan webhook dengan mengeluarkan permintaan POST ke /mint/organizations/{org_name}/webhooks/{webhook_id}, seperti yang Anda lakukan saat memperbarui webhook, dan tetapkan atribut yang diaktifkan dalam isi permintaan ke benar atau salah. Jika Anda menonaktifkan webhook, webhook tidak akan dipicu saat peristiwa terjadi.

Misalnya, kode berikut mengaktifkan webhook3:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "enabled": "true"
  }' \
  -u email:password

Berikut ini contoh responsnya:

{
  "created": 1460385534555,
  "enabled": true,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Menghapus webhook menggunakan API

Hapus webhook dengan mengeluarkan permintaan DELETE ke /mint/organizations/{org_name}/webhooks/{webhook_id}.

Untuk menentukan apakah akan memaksa penghapusan webhook atau tidak jika ada proses yang sedang berlangsung, tetapkan parameter kueri forceDelete ke true atau false. Parameter kueri forceDelete diaktifkan (true) secara default.

Misalnya, kode berikut akan menghapus webhook3:

curl -X DELETE "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

Menyiapkan pengendali callback

Berikut adalah format permintaan JSON yang dikirim ke pengendali callback yang ditentukan oleh webhook saat notifikasi peristiwa dipicu. Anda harus memastikan bahwa pengendali callback memproses permintaan dengan benar.

{
        "orgName": "{org_id}",
        "developerEmail": "{dev_email}",
        "developerFirstName": "{first_name}",
        "developerLastName": "{last_name}",
        "companyName": "{company_name}",
        "applicationName": "{app_name}",
        "packageName": "{api_package_name}",
        "packageId": "{api_package_id}",
        "ratePlanId": "{rateplan_id}",
        "ratePlanName": "{rateplan_name}",
        "ratePlanType": "{rateplan_type}",
        "developerRatePlanQuotaTarget": {quota_target},
        "quotaPercentUsed": {percentage_quota_used},
        "ratePlanStartDate": {rateplan_startdate}, 
        "ratePlanEndDate": {rateplan_enddate},
        "nextBillingCycleStartDate": {next_billing_cycle_startdate},
        "products": ["{api_product_name}","{api_product_name}"],
        "developerCustomAttributes": [],
        "triggerTime": {trigger_time},
        "triggerReason": "{trigger_reason}",
        "developerQuotaResetDate": "{devquota_resetdate}"
}

Menyiapkan notifikasi untuk paket tarif yang dapat disesuaikan

Siapkan notifikasi menggunakan webhook untuk paket tarif yang dapat disesuaikan menggunakan UI atau API.

Menyiapkan notifikasi untuk rencana tarif yang dapat disesuaikan menggunakan UI

Siapkan notifikasi menggunakan webhook untuk paket tarif yang dapat disesuaikan menggunakan UI, seperti yang dijelaskan di bawah.

Akses dialog Notifikasi untuk paket tarif yang dapat disesuaikan

Akses dialog Notifikasi untuk paket tarif yang dapat disesuaikan, seperti yang dijelaskan di bawah.

Edge

Untuk mengakses dialog notifikasi menggunakan UI Edge:

  1. Buat dan publikasikan paket tarif notifikasi yang dapat disesuaikan, seperti yang dijelaskan dalam Menentukan detail paket notifikasi yang dapat disesuaikan.
  2. Akses halaman Tarif Paket dengan memilih Publikasi > Monetisasi > Tarif Paket di menu navigasi sebelah kiri.
  3. Posisikan kursor di atas rencana Tingkat notifikasi yang dapat disesuaikan yang dipublikasikan untuk menampilkan tindakan.
  4. Klik +Beri tahu.

    Dialog Notifikasi akan ditampilkan.

    Catatan: Paket tarif harus dipublikasikan agar tindakan +Beri tahu ditampilkan.

Edge Klasik (Private Cloud)

Untuk mengakses halaman Notifikasi:

  1. Buat paket tarif notifikasi yang dapat disesuaikan, seperti yang dijelaskan dalam Menentukan detail paket notifikasi yang dapat disesuaikan.
  2. Pilih Publish > Packages untuk melihat paket tarif.
  3. Klik +Beri tahu di kolom Tindakan untuk paket tarif.

    Dialog Notifikasi akan ditampilkan.

Menambahkan notifikasi untuk paket tarif yang dapat disesuaikan menggunakan UI

Untuk menambahkan notifikasi untuk paket tarif yang dapat disesuaikan, UI:

  1. Akses Dialog notifikasi.
  2. Tetapkan kondisi notifikasi di bagian Interval Notifikasi dengan menentukan persentase jumlah target transaksi pada saat Anda ingin notifikasi dipicu. Secara khusus:
    • Untuk menetapkan persentase yang tepat, masukkan persentase di kolom At/From % dan biarkan kolom To % kosong.
    • Untuk menetapkan rentang persentase, masukkan persentase awal dan akhir di kolom At/From % dan To %, dan nilai inkremental di kolom Step %. Secara default, notifikasi dikirim dalam penambahan 10% dalam rentang yang ditentukan.

    Kolom Notify At diperbarui untuk mencerminkan setiap persentase dari jumlah target transaksi yang akan memicu peristiwa.

  3. Untuk menetapkan kondisi notifikasi tambahan, klik +Tambahkan dan ulangi langkah 4.
  4. Tetapkan tindakan notifikasi di bagian Webhook dengan memilih satu atau beberapa webhook untuk mengelola penanganan callback saat notifikasi dipicu.
  5. Klik Buat Notifikasi.

Mengedit notifikasi untuk rencana tarif yang dapat disesuaikan menggunakan UI

Guna mengedit notifikasi untuk rencana tarif yang dapat disesuaikan, UI-nya:

  1. Akses dialog Notifikasi.
  2. Klik +Beri tahu di kolom Tindakan untuk paket tarif.
  3. Klik Edit.
  4. Ubah nilai, sesuai kebutuhan.
  5. Klik Simpan Notifikasi.

Menghapus notifikasi untuk paket tarif yang dapat disesuaikan menggunakan UI

Untuk menghapus kondisi dan tindakan notifikasi:

  1. Akses dialog Notifikasi.
  2. Klik +Beri tahu di kolom Tindakan untuk paket tarif.
  3. Klik Hapus Notifikasi.

Menyiapkan notifikasi untuk paket tarif yang dapat disesuaikan menggunakan API

Untuk menyiapkan notifikasi untuk paket tarif yang dapat disesuaikan menggunakan API, gunakan prosedur yang dijelaskan dalam Mengelola kondisi dan tindakan notifikasi menggunakan API dan gunakan atribut yang dijelaskan di bagian ini.

Untuk menyiapkan kondisi notifikasi (notificationCondition), gunakan nilai atribut berikut. Untuk informasi selengkapnya, lihat Properti konfigurasi untuk kondisi notifikasi.

Atribut Nilai
RATEPLAN ID paket tarif notifikasi yang dapat disesuaikan.
PUBLISHED TRUE untuk menunjukkan bahwa paket tarif notifikasi yang dapat disesuaikan harus dipublikasikan.
UsageTarget Persentase jumlah target transaksi saat Anda ingin notifikasi dipicu.

Atribut ini memungkinkan Anda memberi tahu developer saat mereka mendekati atau telah mencapai jumlah transaksi target untuk paket kartu tarif notifikasi yang dapat disesuaikan yang telah mereka beli. Misalnya, jika developer telah membeli paket tarif notifikasi yang dapat disesuaikan dan jumlah target transaksi untuk developer telah ditetapkan ke 1.000, Anda dapat memberi tahu mereka saat mereka mencapai 800 transaksi (80% dari jumlah target transaksi), 1.000 transaksi (100%), atau 1.500 transaksi (150%).

  • Untuk menetapkan persentase yang tepat, masukkan %= n. Misalnya, %= 80 akan mengirim notifikasi saat persentase jumlah transaksi target mencapai 80%.
  • Untuk menetapkan rentang persentase, masukkan persentase awal dan akhir, serta nilai yang akan bertambah sebagai berikut: %= start to end by n. Misalnya, nilai %= 80 to 100 by 10 akan mengirim notifikasi saat persentase jumlah transaksi target mencapai 80%, 90%, dan 100%.

Untuk menyiapkan tindakan notifikasi, di bagian actions, tetapkan nilai berikut. Untuk informasi selengkapnya, lihat Properti konfigurasi untuk tindakan notifikasi.

Atribut Nilai
actionAttribute WEBHOOK untuk memicu webhook.
value ID webhook yang Anda tentukan di bagian sebelumnya, Membuat webhook menggunakan API.

Berikut adalah contoh cara membuat kondisi notifikasi yang memicu webhook saat persentase jumlah transaksi target mencapai 80%, 90%, 100%, 110%, dan 120%.

{
    "notificationCondition": [
      {
        "attribute": "RATEPLAN",
        "value": "123456"
      },
      {
        "attribute": "PUBLISHED",
        "value": "TRUE"
      },
      {
        "attribute": "UsageTarget",
        "value": "%= 80 to 120 by 10"
      }
    } 
    ],
   "actions": [{
          "actionAttribute": "WEBHOOK",
          "value": "b0d77596-142e-4606-ae2d-f55c3c6bfebe",
        }]
  }

Untuk informasi tentang cara melihat, memperbarui, dan menghapus kondisi dan tindakan notifikasi, lihat:

Kode respons webhook

Berikut adalah ringkasan kode respons webhook dan cara kode tersebut ditafsirkan oleh sistem.

Kode Respons Deskripsi
2xx Berhasil
5xx

Permintaan gagal. Sistem akan mencoba kembali permintaan hingga tiga kali dalam interval 5 menit.

Catatan: Waktu tunggu baca dan koneksi untuk permintaan webhook masing-masing adalah 3 detik, yang dapat mengakibatkan permintaan gagal.
Other response Permintaan gagal. Sistem tidak akan mencoba lagi permintaan tersebut.