Webhook

Webhook memungkinkan Anda menerima notifikasi waktu nyata saat ada peristiwa yang terjadi di akun LabelGrid Anda. Gunakan webhook untuk mengotomatiskan alur kerja dan berintegrasi dengan sistem eksternal.

Catatan

Webhook membutuhkan akses API yang aktif pada akun Anda. Hubungi dukungan jika Anda perlu mengaktifkan fitur ini.

Untuk Pengembang: Anda juga dapat mengelola webhook secara terprogram melalui API. Lihat Dokumentasi API LabelGrid untuk endpoint dan contohnya.

Cara Kerja Webhook

1. Anda mengonfigurasi webhook - Tentukan URL dan peristiwa apa saja yang ingin didengarkan
2. Sebuah peristiwa terjadi - Misalnya, sebuah rilis dikirimkan ke toko
3. LabelGrid mengirim permintaan POST - Server Anda menerima data peristiwa tersebut
4. Sistem Anda memprosesnya - Otomatiskan alur kerja berdasarkan peristiwa tersebut

---

Mengakses Webhook

1. Klik ikon profil Anda di pojok kanan atas
2. Pilih Webhooks dari menu turun

---

Membuat Webhook

1. Klik Create Webhook
2. Masukkan Name untuk menandai webhook ini
3. Masukkan URL tempat Anda ingin menerima notifikasi
4. Pilih Events mana yang akan memicu webhook ini
5. Klik Create

Secret Webhook

Saat membuat webhook, Anda akan menerima sebuah secret key. Gunakan ini untuk memverifikasi bahwa permintaan yang masuk benar-benar berasal dari LabelGrid:

• Simpan secret dengan aman
• Verifikasi signature pada permintaan yang masuk
• Jika bocor, buat ulang secret-nya

---

Peristiwa yang Tersedia

Konfigurasikan webhook Anda untuk mendengarkan peristiwa berikut. Event Identifier adalah nilai yang akan Anda lihat pada properti event di payload dan pada header X-Webhook-Event:

Event Identifier	Deskripsi
delivery.completed	Dipicu saat sebuah rilis berhasil dikirimkan ke sebuah outlet
delivery.failed	Dipicu saat pengiriman ke sebuah outlet gagal
takedown.completed	Dipicu saat permintaan takedown selesai
release.review.status_changed	Dipicu saat status peninjauan sebuah rilis berubah
release.preflight.report_ready	Dipicu saat laporan Preflight QC untuk rilis yang ditahan siap diambil
stream_radar.flag_created	Dipicu saat sebuah tanda Stream Radar dimunculkan, atau tanda yang telah terselesaikan terbuka kembali pada deteksi baru
stream_radar.flag_resolved	Dipicu saat sebuah tanda Stream Radar terselesaikan karena deteksi berhenti
release.distributed	Dipicu saat sebuah rilis didistribusikan
payment.statement_ready	Dipicu saat laporan pembayaran siap untuk dilihat
transcode.completed	Dipicu saat transcode audio sebuah track selesai dengan sukses
transcode.failed	Dipicu saat transcode sebuah track gagal atau berakhir tidak lengkap
distribution.outlet.status_changed	Dipicu pada setiap transisi status distribusi per outlet

Anda dapat memilih beberapa peristiwa untuk satu webhook, atau membuat webhook terpisah untuk jenis peristiwa yang berbeda.

Anda juga dapat membaca daftar ini secara terprogram: GET /api/public/webhook/event-types mengembalikan setiap peristiwa beserta skema data yang menjelaskan kunci dan tipe payload-nya, sehingga konsumen dengan skema ketat dapat memperluas validasi masukannya lebih awal.

---

Mengelola Webhook

Melihat Webhook Anda

Daftar webhook menampilkan:

Kolom	Deskripsi
Name	Nama webhook yang Anda tetapkan
URL	Tempat notifikasi dikirim
Events	Jumlah peristiwa yang dikonfigurasi
Status	Active atau Inactive
Success / Fail	Jumlah pengiriman yang berhasil dan gagal
Last Triggered	Kapan webhook terakhir kali dipanggil

Menyunting Webhook

1. Klik tindakan Edit pada baris webhook
2. Ubah nama, URL, atau peristiwa
3. Klik Save

Mengaktifkan / Menonaktifkan

Alihkan status aktif webhook tanpa menghapusnya:

• Active - Webhook akan menerima notifikasi
• Inactive - Webhook dijeda, tidak ada notifikasi yang dikirim

Menghapus Webhook

1. Klik tindakan Delete pada baris webhook
2. Konfirmasikan penghapusan

Bahaya

Webhook yang sudah dihapus tidak dapat dipulihkan.

---

Menguji Webhook

Sebelum mengandalkan sebuah webhook di produksi, ujilah terlebih dahulu:

1. Klik tindakan Test pada webhook Anda
2. LabelGrid mengirimkan payload uji ke URL Anda
3. Pastikan endpoint Anda menerima dan memprosesnya dengan benar

Catatan

Payload uji tidak mengikuti bentuk peristiwa yang sebenarnya. Field event pada amplopnya bernilai "test" dan objek data berisi { "test": true, "message": "...", "timestamp": "..." }. Gunakan ini untuk memverifikasi konektivitas dan penanganan signature, tetapi tulislah penangan peristiwa Anda berdasarkan payload peristiwa sebenarnya yang didokumentasikan di Payload Peristiwa.

---

Melihat Log Webhook

Pantau aktivitas webhook dan atasi masalah:

1. Klik tindakan View Logs pada sebuah webhook
2. Lihat riwayat seluruh pengiriman webhook

Detail Log

Setiap entri log menampilkan:

Field	Deskripsi
Event Type	Peristiwa apa yang memicu pengiriman ini
Response Status	Kode status HTTP dari server Anda
Duration	Berapa lama permintaan tersebut berlangsung
Attempt	Nomor percobaan ulang
Timestamp	Kapan pengiriman terjadi

---

Format Payload Webhook

Saat sebuah peristiwa terjadi, LabelGrid mengirim permintaan POST ke URL Anda dengan payload JSON:

{
  "event": "delivery.completed",
  "timestamp": "2026-05-05T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    // Event-specific data
  }
}

Field timestamp menggunakan format ISO 8601. webhook_id adalah ID webhook yang Anda konfigurasi (nilainya cocok dengan header X-Webhook-Id).

---

Payload Peristiwa

Struktur objek data bergantung pada jenis event. Semua tipe field di bawah ini adalah tipe JSON sebagaimana diserialisasikan dalam payload.

delivery.completed

Dipicu satu kali per outlet saat pengiriman sebuah rilis mencapai status keberhasilan akhir.

{
  "event": "delivery.completed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "status": "complete"
  }
}

Field	Tipe	Deskripsi
distro_queue_id	integer	ID antrean internal untuk percobaan pengiriman ini
release_id	integer	Rilis yang dikirimkan
label_id	integer	Label pemilik rilis, sehingga Anda dapat mengarahkan peristiwa tanpa pencarian lanjutan
release_cat	string | null	Referensi katalog rilis Anda
outlet_id	integer | null	ID outlet tujuan
outlet_name	string | null	Nama outlet yang mudah dibaca (mis. "Spotify")
status	string	Selalu "complete" untuk peristiwa ini

delivery.failed

Dipicu satu kali per outlet saat pengiriman sebuah rilis mencapai status kegagalan akhir. Payload-nya sama dengan delivery.completed ditambah field message.

{
  "event": "delivery.failed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "status": "error",
    "message": "Outlet rejected the delivery: missing ISRC."
  }
}

Field	Tipe	Deskripsi
status	string	Salah satu dari error, fault, rejected, batch_exception
message	string | null	Alasan kegagalan dari outlet atau pipeline distribusi

Catatan

Kegagalan infrastruktur internal (misalnya, kegagalan menyalin berkas audio ke server pengiriman kami) tidak memicu delivery.failed. Hanya kegagalan di sisi DSP dan di tingkat pipeline yang memicu peristiwa ini.

takedown.completed

Dipicu satu kali per outlet saat permintaan takedown berhasil. Bentuknya sama dengan delivery.completed ditambah flag takedown: true.

{
  "event": "takedown.completed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "status": "complete",
    "takedown": true
  }
}

release.distributed

Dipicu satu kali per rilis saat rilis beralih ke status pengiriman distributed. Hanya dipicu pada saat peralihan menjadi distributed, bukan pada penyimpanan berikutnya selama rilis sudah berstatus distributed.

{
  "event": "release.distributed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "release_title": "Summer EP",
    "delivery_status": "distributed"
  }
}

release.review.status_changed

Dipicu setiap kali sebuah rilis berpindah antar status peninjauan.

{
  "event": "release.review.status_changed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "release_title": "Summer EP",
    "previous_status": "to_review",
    "new_status": "approved"
  }
}

Field	Tipe	Deskripsi
previous_status	string	Status sebelumnya. Salah satu dari draft, to_review, approved, rejected, require_changes, audit
new_status	string	Status baru. Kumpulan nilai yang sama
review_issues	array (opsional)	Hadir hanya pada transisi require_changes dan rejected: masalah yang memerlukan perhatian Anda. Kunci ini dihilangkan pada setiap transisi lain, jadi jangan anggap selalu ada

Catatan

Status audit menandakan pemeriksaan ulang issue yang diprakarsai operator terhadap sebuah rilis yang sudah disetujui. Status ini tidak pernah dipicu oleh tindakan Anda sendiri, dan rilis yang berstatus audit tetap aktif di DSP selama pemeriksaan ulang berjalan.

release.preflight.report_ready

Dipicu saat laporan kualitas Preflight QC untuk sebuah rilis yang berada dalam penahanan pra-tinjauan siap diambil. Membutuhkan pengaya Preflight QC pada akun Anda.

{
  "event": "release.preflight.report_ready",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "release_title": "Summer EP",
    "generated_at": "2026-07-07T09:58:12+00:00",
    "profile": { "name": "quality_report", "version": 2 },
    "counts": { "blocking": 1, "informational": 2, "requires_feedback": 1 }
  }
}

Field	Tipe	Deskripsi
release_id	integer	Rilis tempat laporan ini berada
label_id	integer	Label pemilik rilis
release_cat	string | null	Referensi katalog rilis Anda
release_title	string | null	Judul rilis
generated_at	string	Kapan pemeriksaan selesai (ISO 8601). Cocok dengan report.generated_at pada endpoint laporan kualitas
profile	object	Profil kualitas yang digunakan untuk menghitung jumlah: {name, version}
counts	object	Hanya jumlah agregat: {blocking, informational, requires_feedback}. Jumlah requires_feedback tumpang tindih dengan dua lainnya

Catatan

Payload tidak pernah membawa masalahnya sendiri. Saat menerimanya, ambil laporan lengkap dari endpoint laporan kualitas. Lihat Preflight QC: menggunakan API.

stream_radar.flag_created

Dipicu saat sebuah tanda Stream Radar dimunculkan — baik sebuah tanda yang benar-benar baru maupun tanda yang sebelumnya terselesaikan yang terbuka kembali pada deteksi baru. Membutuhkan pengaya Stream Radar pada akun Anda. Field transition membedakan kedua kasus: published untuk tanda baru, reopened untuk tanda yang menjadi aktif kembali.

{
  "event": "stream_radar.flag_created",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "flag_id": 4501,
    "dsp": "spotify",
    "isrc": "USRC12345678",
    "release_id": 789,
    "track_id": 654,
    "severity": "high",
    "status": "active",
    "transition": "published",
    "first_detected_at": "2026-07-06T00:00:00+00:00",
    "last_detected_at": "2026-07-07T00:00:00+00:00",
    "estimated_affected_streams": 12500,
    "published_at": "2026-07-07T09:58:12+00:00",
    "resolved_at": null
  }
}

Field	Tipe	Deskripsi
flag_id	integer	Pengidentifikasi tanda yang stabil; cocok dengan id pada endpoint Stream Radar
dsp	string	Platform tempat pola terlihat (mis. spotify)
isrc	string	ISRC rekaman yang terlibat
release_id	integer	Rilis tempat rekaman itu berada
track_id	integer | null	Trek spesifik, ketika ISRC memetakan secara jelas ke salah satu trek Anda
severity	string	low, medium, atau high
status	string	active untuk peristiwa ini
transition	string	published untuk tanda baru, reopened ketika tanda yang terselesaikan menjadi aktif kembali
first_detected_at	string | null	Kapan pola pertama kali terlihat untuk trek dan platform ini (ISO 8601)
last_detected_at	string | null	Deteksi terbaru (ISO 8601)
estimated_affected_streams	integer | null	Perkiraan berapa banyak stream yang terlibat
published_at	string	Kapan tanda pertama kali dimunculkan kepada Anda (ISO 8601)
resolved_at	string | null	null selama tanda aktif

stream_radar.flag_resolved

Dipicu saat sebuah tanda Stream Radar terselesaikan karena deteksi berhenti. Membutuhkan pengaya Stream Radar. Field-nya sama seperti stream_radar.flag_created (tanpa transition), dengan status yang bernilai resolved dan resolved_at yang terisi.

{
  "event": "stream_radar.flag_resolved",
  "timestamp": "2026-07-14T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "flag_id": 4501,
    "dsp": "spotify",
    "isrc": "USRC12345678",
    "release_id": 789,
    "track_id": 654,
    "severity": "high",
    "status": "resolved",
    "first_detected_at": "2026-07-06T00:00:00+00:00",
    "last_detected_at": "2026-07-12T00:00:00+00:00",
    "estimated_affected_streams": 18700,
    "published_at": "2026-07-07T09:58:12+00:00",
    "resolved_at": "2026-07-14T09:55:03+00:00"
  }
}

Catatan

Pengiriman webhook Stream Radar bersifat upaya-terbaik (best-effort). Perlakukan endpoint tanda Stream Radar sebagai sumber kebenaran dan gunakan peristiwa ini sebagai pengingat untuk membaca keadaan saat ini. Lihat Stream Radar: menggunakan API.

payment.statement_ready

Dipicu saat laporan pembayaran dibuat dan siap untuk dilihat.

{
  "event": "payment.statement_ready",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "payment_request_id": 1024,
    "invoice_number": "INV-2026-001",
    "period": "2026-04-30",
    "amount": 1234.56,
    "total_due_usd": 1234.56,
    "currency": "USD"
  }
}

Field	Tipe	Deskripsi
payment_request_id	integer	ID permintaan pembayaran internal
invoice_number	string	Referensi faktur untuk laporan tersebut
period	string | null	Tanggal akhir periode (tanggal ISO 8601, YYYY-MM-DD)
amount	number	Jumlah laporan dalam currency
total_due_usd	number	Total laporan yang dikonversi ke USD
currency	string	Kode mata uang ISO 4217 (default-nya USD)

Catatan

payment.statement_ready bercakupan akun: tidak membawa release_id maupun label_id.

transcode.completed dan transcode.failed

Dipicu saat transcode audio sebuah track selesai. transcode.completed dipicu saat berhasil; transcode.failed dipicu saat transcode gagal atau berakhir tidak lengkap. Keduanya memiliki bentuk payload yang sama.

{
  "event": "transcode.completed",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "track_id": 654,
    "transcoder_queue_id": 987,
    "status": "complete",
    "status_message": "transcode_complete",
    "files": [
      { "asset_type_id": 2, "status": "complete" }
    ]
  }
}

Field	Tipe	Deskripsi
release_id	integer	Rilis tempat track ini berada
label_id	integer	Label pemilik rilis
track_id	integer	Track yang ditranskode
transcoder_queue_id	integer	ID antrean transcode internal
status	string	Status antrean mentah: complete, error, atau incomplete
status_message	string	Kode alasan yang aman dan terenumerasi: transcode_complete, transcode_error, atau transcode_incomplete
files	array	Detail per berkas untuk track: {asset_type_id, status} per berkas yang ditranskode

distribution.outlet.status_changed

Dipicu pada setiap transisi status distribusi per outlet (misalnya scheduled → transcoding → batched → complete), bukan hanya transisi akhir yang dicakup oleh delivery.completed, delivery.failed, dan takedown.completed. Peristiwa ini memang dirancang untuk sering terpicu: berlangganan hanya jika Anda menginginkan seluruh progres per outlet.

{
  "event": "distribution.outlet.status_changed",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "previous_status": "transcoding",
    "status": "batched"
  }
}

Field	Tipe	Deskripsi
distro_queue_id	integer	ID antrean internal untuk pengiriman ini
release_id	integer	Rilis yang sedang didistribusikan
label_id	integer	Label pemilik rilis
release_cat	string | null	Referensi katalog rilis Anda
outlet_id	integer | null	ID outlet tujuan
outlet_name	string | null	Nama outlet yang mudah dibaca
previous_status	string | null	Status sebelumnya; null jika baris tidak punya status sebelumnya yang dikenali
status	string	Status baru

---

Memverifikasi Signature Webhook

Setiap pengiriman webhook ditandatangani sehingga Anda dapat memverifikasi bahwa pengiriman tersebut memang berasal dari LabelGrid. Selalu verifikasi signature sebelum memproses peristiwa.

Header Permintaan

Setiap permintaan POST webhook menyertakan header berikut:

Header	Deskripsi
X-Webhook-Signature	HMAC-SHA256 dari body permintaan mentah, heksadesimal huruf kecil, tanpa awalan algoritma
X-Webhook-Timestamp	Timestamp ISO 8601 pengiriman (nilainya sama dengan properti timestamp di body)
X-Webhook-Event	Pengidentifikasi peristiwa (mis. delivery.completed)
X-Webhook-Id	ID webhook yang menerima pengiriman
User-Agent	LabelGrid-Webhooks/1.0
Content-Type	application/json

Algoritma

• Algoritma: HMAC-SHA256
• Pengodean: Heksadesimal huruf kecil
• Awalan: Tidak ada; nilainya hanya berupa hex digest, bukan sha256=...
• Konten yang ditandatangani: Seluruh body permintaan JSON mentah (body itu sendiri menyertakan timestamp sebagai properti, sehingga timestamp ikut ditandatangani secara implisit)

Resep Verifikasi

1. Baca body permintaan mentah sebelum parsing atau transformasi JSON apa pun. Menserialisasi ulang JSON yang sudah diparsing dapat menghasilkan byte yang berbeda dan merusak signature.
2. Hitung HMAC-SHA256(raw_body, your_webhook_secret) lalu ambil hex digest huruf kecilnya.
3. Bandingkan dengan X-Webhook-Signature menggunakan perbandingan constant-time.
4. (Disarankan) Tolak permintaan jika X-Webhook-Timestamp lebih lama dari jendela toleransi replay Anda; kami menyarankan 5 menit.

Contoh PHP

$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';

$expected = hash_hmac('sha256', $rawBody, $webhookSecret);

if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Reject deliveries older than 5 minutes
if (abs(time() - strtotime($timestamp)) > 300) {
    http_response_code(401);
    exit('Stale delivery');
}

$payload = json_decode($rawBody, true);
// ... process the event
http_response_code(200);

Contoh Node.js

const crypto = require('crypto');

// Express: capture raw body BEFORE any JSON middleware
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body; // Buffer
  const signature = req.header('X-Webhook-Signature') || '';
  const timestamp = req.header('X-Webhook-Timestamp') || '';

  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');

  const sigBuf = Buffer.from(signature, 'hex');
  const expBuf = Buffer.from(expected, 'hex');

  if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
    return res.status(401).send('Invalid signature');
  }

  if (Math.abs(Date.now() - new Date(timestamp).getTime()) > 5 * 60 * 1000) {
    return res.status(401).send('Stale delivery');
  }

  const payload = JSON.parse(rawBody.toString('utf8'));
  // ... process the event
  res.sendStatus(200);
});

Contoh Python

import hmac, hashlib
from datetime import datetime, timezone

raw_body = request.get_data()  # Flask: bytes, before any JSON parsing
signature = request.headers.get('X-Webhook-Signature', '')
timestamp = request.headers.get('X-Webhook-Timestamp', '')

expected = hmac.new(
    webhook_secret.encode('utf-8'),
    raw_body,
    hashlib.sha256
).hexdigest()

if not hmac.compare_digest(expected, signature):
    return ('Invalid signature', 401)

delivery_time = datetime.fromisoformat(timestamp.replace('Z', '+00:00'))
if abs((datetime.now(timezone.utc) - delivery_time).total_seconds()) > 300:
    return ('Stale delivery', 401)

return ('', 200)  # process the event, then ack

Kesalahan yang Sering Terjadi

• Menserialisasi ulang body sebelum hashing. Framework yang otomatis memparsing JSON (Express express.json(), body permintaan default Laravel) kehilangan byte aslinya. Tangkap body mentah terlebih dahulu.
• Menggunakan perbandingan yang bukan constant-time (==, ===). Rentan terhadap serangan timing; selalu gunakan hash_equals (PHP), crypto.timingSafeEqual (Node), hmac.compare_digest (Python), atau padanannya di bahasa Anda.
• Mengharapkan awalan sha256=. Nilai header hanyalah hex digest tanpa awalan.
• Melewatkan pemeriksaan timestamp. Tanpa itu, signature yang bocor dapat diputar ulang tanpa batas.

---

Batasan dan Keandalan

Batasan Permintaan

Batasan	Nilai
Batas waktu permintaan	10 detik
Ukuran payload maksimum	64 KB
Webhook maksimum per pengguna	10

Jika endpoint Anda tidak merespons dalam 10 detik, pengiriman dianggap gagal dan dicoba ulang.

Jadwal Percobaan Ulang

Jika endpoint Anda mengembalikan status non-2xx atau melewati batas waktu, LabelGrid mencoba ulang dengan backoff eksponensial:

Percobaan	Jeda sebelum percobaan ulang
1 → 2	30 detik
2 → 3	1 menit
3 → 4	2 menit
4 → 5	4 menit
5 → 6	8 menit
6 → 7	16 menit
7 → 8	32 menit
8 → 9	64 menit
9 → 10	128 menit

Setiap interval mencakup jitter 0–30 detik. Setelah 10 percobaan (total waktu berlalu sekitar 4,5 jam), pengiriman dicatat sebagai gagal permanen dan tidak dicoba ulang lagi.

Penonaktifan Otomatis

Jika endpoint sebuah webhook terus gagal — kegagalan pengiriman berturut-turut tanpa satu pun pengiriman berhasil di antaranya — LabelGrid menonaktifkan webhook tersebut secara otomatis agar berhenti mencoba ulang endpoint yang jelas tidak dapat menerima event. Penghitung kegagalan direset pada setiap pengiriman yang berhasil, sehingga gangguan sesekali tidak pernah menonaktifkan webhook; hanya kegagalan yang berkelanjutan dan tanpa henti yang melakukannya.

Ketika sebuah webhook dinonaktifkan dengan cara ini, pemiliknya menerima email. Email tersebut menyebutkan nama webhook dan URL endpoint-nya, serta jenis kegagalan yang memicu penonaktifan — misalnya waktu koneksi habis atau error HTTP yang berulang.

Mengaktifkan kembali bisa Anda lakukan sendiri: perbaiki endpoint Anda, lalu aktifkan kembali webhook di Profil → Webhooks. Mengaktifkan kembali webhook yang dinonaktifkan akan mereset penghitung kegagalannya. Daftar webhook menampilkan status aktif dan jumlah kegagalan terkini setiap webhook, sehingga Anda dapat mengenali endpoint bermasalah secara sekilas.

Praktik Terbaik untuk Keandalan

• Kembalikan respons 2xx dengan cepat (dalam 10 detik)
• Proses data secara asinkron setelah memberi konfirmasi
• Verifikasi signature pada setiap permintaan (lihat Memverifikasi Signature Webhook)
• Pantau hitungan kegagalan Anda dalam daftar webhook
• Periksa log pengiriman saat menyelidiki peristiwa yang terlewat

---

Kasus Penggunaan

Notifikasi Otomatis

• Kirim pesan Slack saat rilis tayang
• Kirim email ke tim Anda saat pengiriman gagal
• Perbarui dasbor internal

Otomasi Alur Kerja

• Picu kampanye pemasaran saat rilis didistribusikan
• Perbarui situs web Anda saat konten baru tersedia
• Sinkronkan status ke alat manajemen proyek eksternal

Pemantauan dan Peringatan

• Dapatkan peringatan seketika untuk kegagalan pengiriman
• Pantau perkembangan distribusi secara waktu nyata
• Pantau perubahan status peninjauan

---

Pemecahan Masalah

Webhook Tidak Menerima Peristiwa

1. Periksa status - Apakah webhook berstatus Active?
2. Verifikasi URL - Apakah endpoint dapat diakses dari internet?
3. Periksa peristiwa - Apakah peristiwa yang tepat sudah dipilih?
4. Tinjau log - Adakah kesalahan yang tercatat?

Hitungan Kegagalan Tinggi

1. Periksa endpoint Anda - Apakah mengembalikan 200 OK?
2. Periksa waktu respons - Apakah merespons dalam batas waktu?
3. Tinjau pesan kesalahan - Apa yang gagal?
4. Uji secara manual - Kirim webhook uji

Membuat Ulang Secret

Jika secret webhook Anda bocor:

1. Klik Regenerate Secret di pengaturan webhook
2. Perbarui aplikasi Anda dengan secret baru
3. Secret lama langsung berhenti berfungsi

---

Butuh Bantuan?

Jika Anda memiliki pertanyaan tentang webhook, hubungi tim dukungan kami.