Webhook

Webhook adalah konfigurasi yang mengirim permintaan HTTP ke URL eksternal yang telah ditentukan ketika terjadi sesuatu di Space (misalnya pembuatan atau publikasi Content). Digunakan untuk integrasi sistem eksternal atau otomatisasi. Misalnya, Anda dapat mengonfigurasinya untuk memanggil server notifikasi internal atau memanggil API eksternal setiap kali sebuah Content produk dipublikasikan.

Webhook tidak berhenti pada pengiriman permintaan saja, tetapi juga dapat menerima respons tersebut dan menulisnya kembali ke Content atau Media melalui WriteBack. Beginilah cara Anda menyusun alur kerja asinkron yang menyerap hasil API eksternal menjadi data di dalam Space. Webhook adalah sumber daya turunan dari Space di CMA, dan jalurnya berbasis pada /spaces/{spaceId}/webhooks.

Struktur sumber daya

Berikut adalah respons pengambilan tunggal dari Webhook "Notifikasi perubahan produk". Bersama dengan sys (properti sistem), ia memiliki field konfigurasi seperti tujuan pengiriman, event yang dilanggan, dan kondisi pemicu.

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PWhk01Examp",
    "type": "Webhook",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T11:30:00.000Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T11:30:00.000Z",
    "version": 1
  },
  "name": "Notifikasi perubahan produk",
  "filters": [
    { "doc": "sys.contentType.sys.id", "op": "EQ", "value": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" }
  ],
  "headers": [
    { "key": "X-Source", "value": "weegloo", "secret": false }
  ],
  "httpBasicUsername": "dailywear",
  "topics": ["Content.Create", "Content.Publish"],
  "transformation": { "method": "POST", "contentType": "application/json", "includeBody": true },
  "url": "https://api.dailywear.example/webhooks/products",
  "activate": true
}

Kunci utama:

• sys.id: Pengenal unik Webhook. Dimasukkan ke dalam {webhookId} pada jalur pengambilan tunggal, perubahan, dan penghapusan.
• url: URL tujuan eksternal yang dipanggil ketika event terjadi.
• topics: Array yang menentukan event mana yang akan dilanggan. Formatnya dijelaskan di topics di bawah.
• filters: Kondisi yang benar-benar memicu di antara event yang dilanggan. Dijelaskan di filters di bawah.
• transformation: Konfigurasi yang mengubah bentuk permintaan keluar (metode, body, dll.). Dijelaskan di transformation di bawah.
• writeBacks: Array pekerjaan yang menerima respons eksternal dan menulisnya kembali ke Content atau Media. Tidak ada pada contoh di atas. Dijelaskan di writeBacks di bawah.

Properti sistem (sys)

Setiap Webhook menyimpan properti sistem umum dalam objek sys. space, createdBy, dan updatedBy dimasukkan dalam bentuk Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Webhook adalah sumber daya konfigurasi, sehingga tidak memiliki konsep publikasi. Berbeda dengan Content atau Content Type, ia tidak memiliki properti status publikasi seperti publish, archive, atau status, dan hanya memiliki version untuk pelacakan perubahan. Menghidupkan dan mematikan dikendalikan bukan oleh publikasi melainkan oleh field body activate.

Properti body

Body Webhook (nilai konfigurasi yang dikirim saat pembuatan dan perubahan, serta yang dikembalikan dalam respons) terdiri dari field berikut.

Setiap item pada headers terdiri dari key (wajib), value (wajib), dan secret (opsional, boolean). Header dengan secret bernilai true nilainya disamarkan pada respons. Letakkan nilai yang tidak boleh terekspos seperti API key pada header dengan secret: true.

topics

Setiap item pada topics berformat {resource}.{action}. Contoh: Content.Create, Content.Publish, Media.Create.

Action adalah salah satu dari berikut, atau * yang berarti semua action dari sumber daya tersebut (contoh: Content.*).

filters

filters adalah array yang mempersempit kondisi yang benar-benar memicu Webhook di antara topics yang dilanggan. Setiap filter berbentuk sebagai berikut.

{ "doc": "sys.contentType.sys.id", "op": "EQ", "value": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" }

• doc: Jalur field yang dibandingkan. Salah satu dari sys.id, sys.contentType.sys.id, sys.createdBy.sys.id, atau sys.updatedBy.sys.id.
• op: Operator perbandingan. Salah satu dari EQ, NE, IN, NOT_IN, REGEX, atau NOT_REGEX.
• value: Nilai pembanding. Berikan string untuk EQ, NE, REGEX, NOT_REGEX, dan array string untuk IN, NOT_IN.

Jika Anda menetapkan beberapa filter, semuanya harus terpenuhi agar memicu (AND). Jika filters dikosongkan, semua event dari topics yang dilanggan akan memicu.

transformation

transformation mengubah bentuk permintaan HTTP keluar. Jika tidak ditentukan, seluruh payload sumber daya dikirim apa adanya dengan POST default.

writeBacks

writeBacks adalah array berurutan dari pekerjaan yang menulis kembali ke Content atau Media menggunakan respons eksternal yang diterima Webhook. Dijalankan secara berurutan hanya ketika API eksternal merespons dengan 2xx. Setiap item memiliki satu $content (WriteBackContent) atau $media (WriteBackMedia).

Kunci WriteBackContent ($content):

Kunci WriteBackMedia ($media):

Berikut adalah contoh writeBacks yang mengekstrak nilai dari JSON respons eksternal untuk membuat satu Content.

"writeBacks": [
  {
    "$content": {
      "action": "Create",
      "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" } },
      "locale": "ko-KR",
      "fields": {
        "productName": "{ /response/title }",
        "price": "{ /response/price }"
      },
      "publish": true,
      "unpublish": true
    }
  }
]

{ /response/... } adalah template JSON Pointer yang mengekstrak nilai dari JSON respons yang diterima Webhook. Kunci pada fields (productName, price) adalah apiName dari field Content sasaran. Contoh di atas mengisi title dari respons ke productName Content, dan price ke price, lalu membuat Content dan mempublikasikannya.

API

Base URL untuk semua endpoint di bawah adalah https://cma.weegloo.com/v1, dan diperlukan Bearer token yang mengautentikasi CMA pada header Authorization. Perubahan (PUT) dan perubahan parsial (PATCH) harus turut mengirim header X-Weegloo-Version (sys.version sumber daya saat ini) untuk kontrol konkurensi optimistis.

Dokumen terkait

• Content: Data body yang dipicu oleh Webhook atau ditulis melalui WriteBack.
• Media: Sumber daya file yang dapat dibuat melalui WriteBack.
• SpaceRole: Ketika membatasi akses Content pekerjaan Webhook dengan :self.