Webhook Laravel: Cara Menerima, Memvalidasi, dan Memproses Event dari Sistem Eksternal
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
Pola penerima webhook yang andal untuk semua penyedia: endpoint tanpa CSRF tetapi berverifikasi tanda tangan, perlindungan replay, penyimpanan payload mentah, idempotensi berdasarkan ID event, respons cepat lalu proses di queue, penanganan event yang datang tidak berurutan, pemrosesan ulang, pemantauan, dan test.
Webhook adalah cara sistem lain memberi tahu aplikasi Anda bahwa sesuatu terjadi: pembayaran berhasil (payment gateway), pesan WhatsApp terkirim (penyedia WhatsApp), atau dokumen ditandatangani (layanan tanda tangan digital). Berbeda dengan API yang Anda panggil, webhook dipanggil oleh pihak luar, kapan saja, dan berulang kali.
Kesalahan umum pada penerima webhook:
| Kesalahan | Akibat |
|---|---|
| Tidak memverifikasi tanda tangan | Siapa pun bisa mengirim "pembayaran berhasil" palsu |
| Memproses langsung di request (kirim email, update banyak tabel) | Respons lambat; penyedia menganggap gagal lalu mengirim ulang |
| Tidak menangani duplikat | Iuran tercatat lunas dua kali, notifikasi terkirim berulang |
| Mengandalkan urutan kedatangan | Status pending datang setelah settlement dan menimpanya |
| Tidak menyimpan payload mentah | Sulit menyelidiki ketika ada selisih data |
| Mengembalikan 500 untuk event yang tidak dikenal | Penyedia terus mencoba ulang selamanya |
Hasil akhir: kerangka penerima webhook yang bisa dipakai ulang untuk penyedia apa pun:
POST /webhooks/{penyedia}
│
├─► Verifikasi tanda tangan + timestamp (tolak 401 bila tidak valid)
├─► Simpan payload mentah ke tabel webhook_calls (unik per event ID)
│ └─ sudah ada? → balas 200, selesai (idempoten)
├─► Dispatch job ProsesWebhook ke queue
└─► Balas 200 dalam hitungan milidetik
│
(queue worker)
▼
Handler per jenis event
(dengan kunci & pemeriksaan status)
| Komponen | Versi |
|---|---|
| PHP | 8.3+ (disarankan 8.4) |
| Laravel | 13.x |
| Queue | Redis atau database, worker berjalan |
| HTTPS | Wajib (penyedia umumnya menolak URL HTTP) |
| Testing | Pest 4 |
| Alternatif paket | spatie/laravel-webhook-client (opsional) |
Sebelum menulis kode, catat dari dokumentasi penyedia:
| Pertanyaan | Contoh jawaban |
|---|---|
| Bagaimana tanda tangan dibuat? | HMAC-SHA256(timestamp + "." + body, secret) di header X-Signature |
| Apakah ada timestamp? | Ya, di header X-Timestamp (detik Unix) |
| Di mana ID unik event? | Field event_id di body |
| Jenis event apa saja? | payment.succeeded, payment.failed, payment.expired |
| Status HTTP apa yang dianggap sukses? | 2xx |
| Bagaimana kebijakan retry? | Diulang hingga 5 kali dengan jeda bertambah |
| Batas waktu respons? | 10 detik |
| Apakah ada daftar IP pengirim? | Ada, tetapi bisa berubah |
Contoh di artikel ini memakai penyedia fiktif dengan skema HMAC di atas. Artikel Panduan Integrasi Payment Gateway di Laravel dan Cara Mengirim Notifikasi WhatsApp dari Laravel menerapkan pola yang sama untuk penyedia nyata.
php artisan make:migration create_webhook_calls_table
Schema::create('webhook_calls', function (Blueprint $table) {
$table->id();
$table->string('penyedia', 30);
$table->string('event_id', 120);
$table->string('jenis', 80)->nullable();
$table->json('headers'); // header terpilih, tanpa secret
$table->longText('payload'); // body mentah, persis seperti diterima
$table->string('status', 15)->default('diterima'); // diterima | diproses | gagal | diabaikan
$table->unsignedSmallInteger('percobaan')->default(0);
$table->text('error')->nullable();
$table->timestamp('diproses_pada')->nullable();
$table->timestamps();
$table->unique(['penyedia', 'event_id']); // kunci idempotensi
$table->index(['status', 'created_at']);
});
// app/Models/WebhookCall.php
namespace App\Models;
use Illuminate\Database\Eloquent\{MassPrunable, Model};
class WebhookCall extends Model
{
use MassPrunable;
protected $guarded = [];
protected function casts(): array
{
return ['headers' => 'array', 'diproses_pada' => 'datetime'];
}
public function data(): array
{
return json_decode($this->payload, true, flags: JSON_THROW_ON_ERROR);
}
public function prunable()
{
return static::where('status', 'diproses')->where('created_at', '<', now()->subDays(180));
}
}
Payload mentah disimpan apa adanya (longText, bukan json), karena verifikasi tanda tangan ulang atau investigasi membutuhkan byte yang persis sama.
// config/webhooks.php
return [
'penyedia' => [
'paybayar' => [
'secret' => env('PAYBAYAR_WEBHOOK_SECRET'),
'secret_lama' => env('PAYBAYAR_WEBHOOK_SECRET_OLD'), // untuk masa rotasi
'toleransi_detik' => 300,
'header_signature' => 'X-Signature',
'header_timestamp' => 'X-Timestamp',
'event_id_path' => 'event_id',
'jenis_path' => 'type',
'handler' => \App\Webhooks\Paybayar\PaybayarHandler::class,
'ip_allowlist' => array_filter(explode(',', (string) env('PAYBAYAR_WEBHOOK_IPS'))),
],
],
];
// app/Webhooks/SignatureVerifier.php
namespace App\Webhooks;
use Illuminate\Http\Request;
final class SignatureVerifier
{
public function __construct(private readonly array $config) {}
public function verify(Request $request): bool
{
$signature = (string) $request->header($this->config['header_signature']);
$timestamp = (string) $request->header($this->config['header_timestamp']);
if ($signature === '' || ! ctype_digit($timestamp)) {
return false;
}
// Perlindungan replay: tolak pesan yang terlalu lama atau dari masa depan
if (abs(time() - (int) $timestamp) > $this->config['toleransi_detik']) {
return false;
}
$body = $request->getContent(); // body MENTAH, bukan $request->all()
foreach (array_filter([$this->config['secret'], $this->config['secret_lama'] ?? null]) as $secret) {
$expected = hash_hmac('sha256', $timestamp.'.'.$body, $secret);
if (hash_equals($expected, $signature)) { // perbandingan waktu-konstan
return true;
}
}
return false;
}
}
Tiga detail yang sering salah:
getContent()). Mengubah urutan field atau spasi lewat json_encode($request->all()) menghasilkan hash yang berbeda.hash_equals(), bukan ===. Perbandingan biasa bisa membocorkan informasi lewat perbedaan waktu eksekusi.Dukungan secret_lama memungkinkan rotasi secret tanpa kehilangan webhook: isi secret baru di penyedia, pertahankan secret lama beberapa hari, lalu hapus.
Bila penyedia memakai skema lain (misalnya hash SHA-512 dari beberapa field seperti Midtrans, atau token statis di header), buat verifier khusus untuk penyedia tersebut dengan prinsip yang sama.
// app/Http/Controllers/WebhookController.php
namespace App\Http\Controllers;
use App\Jobs\ProsesWebhook;
use App\Models\WebhookCall;
use App\Webhooks\SignatureVerifier;
use Illuminate\Database\UniqueConstraintViolationException;
use Illuminate\Http\Request;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Log;
class WebhookController extends Controller
{
public function __invoke(Request $request, string $penyedia)
{
$config = config("webhooks.penyedia.{$penyedia}") ?? abort(404);
if ($config['ip_allowlist'] && ! in_array($request->ip(), $config['ip_allowlist'], true)) {
Log::channel('security')->warning('webhook.ip_ditolak', ['penyedia' => $penyedia, 'ip' => $request->ip()]);
abort(403);
}
if (! (new SignatureVerifier($config))->verify($request)) {
Log::channel('security')->warning('webhook.signature_tidak_valid', ['penyedia' => $penyedia, 'ip' => $request->ip()]);
return response()->json(['message' => 'Tanda tangan tidak valid.'], 401);
}
$data = json_decode($request->getContent(), true);
$eventId = Arr::get($data, $config['event_id_path']);
if (! is_array($data) || ! $eventId) {
return response()->json(['message' => 'Payload tidak valid.'], 400);
}
try {
$call = WebhookCall::create([
'penyedia' => $penyedia,
'event_id' => (string) $eventId,
'jenis' => Arr::get($data, $config['jenis_path']),
'headers' => Arr::only($request->headers->all(), ['content-type', 'user-agent', strtolower($config['header_timestamp'])]),
'payload' => $request->getContent(),
]);
} catch (UniqueConstraintViolationException) {
return response()->json(['message' => 'Sudah diterima.']); // duplikat: idempoten, tetap 200
}
ProsesWebhook::dispatch($call->id)->onQueue('webhooks');
return response()->json(['message' => 'Diterima.']);
}
}
// routes/api.php
Route::post('webhooks/{penyedia}', \App\Http\Controllers\WebhookController::class)
->whereAlpha('penyedia')
->middleware('throttle:webhooks')
->name('webhooks');
// AppServiceProvider::boot()
RateLimiter::for('webhooks', fn (Request $request) => Limit::perMinute(600)->by($request->route('penyedia').'|'.$request->ip()));
Route berada di grup api (tanpa session dan CSRF), sehingga tidak perlu mengecualikan apa pun dari validasi CSRF. Perlindungannya digantikan oleh verifikasi tanda tangan.
Penanganan duplikat mengandalkan indeks unik di database, bukan pemeriksaan exists() lalu create(). Dua request duplikat yang datang bersamaan tetap hanya menghasilkan satu baris.
Simpan headers secara selektif; jangan menyimpan header yang berisi secret atau token.
// app/Jobs/ProsesWebhook.php
namespace App\Jobs;
use App\Models\WebhookCall;
use App\Webhooks\Exceptions\EventDiabaikan;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Middleware\WithoutOverlapping;
class ProsesWebhook implements ShouldQueue
{
use Queueable;
public int $tries = 5;
public array $backoff = [10, 60, 300, 900];
public function __construct(public int $webhookCallId) {}
public function middleware(): array
{
return [(new WithoutOverlapping("webhook:{$this->webhookCallId}"))->releaseAfter(30)];
}
public function handle(): void
{
$call = WebhookCall::findOrFail($this->webhookCallId);
if ($call->status === 'diproses') {
return; // sudah selesai sebelumnya
}
$call->increment('percobaan');
$handler = app(config("webhooks.penyedia.{$call->penyedia}.handler"));
try {
$handler->handle($call->jenis, $call->data(), $call);
$call->update(['status' => 'diproses', 'diproses_pada' => now(), 'error' => null]);
} catch (EventDiabaikan $e) {
$call->update(['status' => 'diabaikan', 'error' => $e->getMessage(), 'diproses_pada' => now()]);
}
}
public function failed(\Throwable $e): void
{
WebhookCall::whereKey($this->webhookCallId)->update([
'status' => 'gagal',
'error' => mb_substr($e->getMessage(), 0, 2000),
]);
report($e);
}
}
Pemisahan ini membuat respons ke penyedia selalu cepat. Bila pemrosesan gagal (misalnya database sedang sibuk), job yang mengulang, bukan penyedia.
// app/Webhooks/Paybayar/PaybayarHandler.php
namespace App\Webhooks\Paybayar;
use App\Models\{Pembayaran, WebhookCall};
use App\Services\Pembayaran\TandaiPembayaran;
use App\Webhooks\Exceptions\EventDiabaikan;
use Illuminate\Support\Facades\DB;
final class PaybayarHandler
{
public function __construct(private readonly TandaiPembayaran $tandai) {}
public function handle(?string $jenis, array $data, WebhookCall $call): void
{
match ($jenis) {
'payment.succeeded' => $this->berhasil($data),
'payment.failed', 'payment.expired' => $this->gagal($data, $jenis),
default => throw new EventDiabaikan("Jenis event tidak ditangani: {$jenis}"),
};
}
private function berhasil(array $data): void
{
DB::transaction(function () use ($data) {
$pembayaran = Pembayaran::where('referensi', $data['payment']['reference'])->lockForUpdate()->first()
?? throw new EventDiabaikan('Referensi pembayaran tidak dikenal.');
// Validasi silang: jumlah dari penyedia harus sama dengan yang kita tagihkan
if ((int) $data['payment']['amount'] !== $pembayaran->jumlah) {
throw new \RuntimeException("Jumlah tidak cocok untuk {$pembayaran->referensi}");
}
if ($pembayaran->status === 'berhasil') {
return; // sudah final: tidak perlu apa-apa
}
$this->tandai->berhasil($pembayaran, dibayarPada: $data['payment']['paid_at']);
});
}
private function gagal(array $data, string $jenis): void
{
DB::transaction(function () use ($data, $jenis) {
$pembayaran = Pembayaran::where('referensi', $data['payment']['reference'])->lockForUpdate()->first();
// Jangan pernah menurunkan status final: event gagal yang datang terlambat diabaikan
if (! $pembayaran || in_array($pembayaran->status, ['berhasil', 'dikembalikan'], true)) {
return;
}
$pembayaran->update(['status' => $jenis === 'payment.expired' ? 'kedaluwarsa' : 'gagal']);
});
}
}
Prinsip pemrosesan:
berhasil, dikembalikan) tidak boleh ditimpa oleh event yang datang terlambat.lockForUpdate) agar dua event untuk pembayaran yang sama tidak diproses bersamaan.Perintah untuk memproses ulang webhook yang gagal setelah bug diperbaiki:
// app/Console/Commands/ProsesUlangWebhook.php
protected $signature = 'webhook:proses-ulang {--id=* : ID webhook_calls} {--status=gagal} {--sejak= : Tanggal Y-m-d}';
public function handle(): int
{
$query = WebhookCall::query()
->when($this->option('id'), fn ($q, $ids) => $q->whereKey($ids))
->when(! $this->option('id'), fn ($q) => $q->where('status', $this->option('status')))
->when($this->option('sejak'), fn ($q, $d) => $q->where('created_at', '>=', $d));
$jumlah = 0;
$query->lazyById()->each(function (WebhookCall $call) use (&$jumlah) {
$call->update(['status' => 'diterima']);
ProsesWebhook::dispatch($call->id)->onQueue('webhooks');
$jumlah++;
});
$this->info("{$jumlah} webhook dijadwalkan ulang.");
return self::SUCCESS;
}
Pemantauan sederhana di scheduler:
// routes/console.php
Schedule::call(function () {
$gagal = WebhookCall::where('status', 'gagal')->where('updated_at', '>=', now()->subHour())->count();
$macet = WebhookCall::where('status', 'diterima')->where('created_at', '<', now()->subMinutes(15))->count();
if ($gagal > 0 || $macet > 0) {
Log::channel('security')->alert('webhook.perlu_perhatian', compact('gagal', 'macet'));
// atau kirim notifikasi ke admin (artikel Sistem Notifikasi Laravel)
}
})->everyFifteenMinutes()->name('pantau-webhook')->onOneServer();
Schedule::command('model:prune', ['--model' => [\App\Models\WebhookCall::class]])->daily();
Webhook yang "macet" di status diterima biasanya berarti queue worker untuk antrean webhooks tidak berjalan.
spatie/laravel-webhook-client menyediakan pola serupa (verifikasi tanda tangan, tabel webhook_calls, job pemroses) lewat konfigurasi. Paket ini cocok bila Anda menerima webhook dari banyak penyedia dan ingin konvensi siap pakai. Prinsip pada artikel ini tetap berlaku: verifikasi timestamp, idempotensi berdasarkan ID event, dan mesin status yang hanya bergerak maju perlu Anda pastikan sendiri di handler.
// tests/Feature/Webhooks/PaybayarWebhookTest.php
use Illuminate\Support\Facades\Queue;
function kirimWebhook(array $payload, ?int $timestamp = null, ?string $secret = null)
{
$body = json_encode($payload);
$ts = (string) ($timestamp ?? time());
$sig = hash_hmac('sha256', $ts.'.'.$body, $secret ?? config('webhooks.penyedia.paybayar.secret'));
return test()->call('POST', '/api/webhooks/paybayar', [], [], [], [
'CONTENT_TYPE' => 'application/json',
'HTTP_X_SIGNATURE' => $sig,
'HTTP_X_TIMESTAMP' => $ts,
], $body);
}
beforeEach(fn () => config(['webhooks.penyedia.paybayar.secret' => 'rahasia-uji', 'webhooks.penyedia.paybayar.ip_allowlist' => []]));
it('menerima webhook valid dan menjadwalkan pemrosesan', function () {
Queue::fake();
kirimWebhook(['event_id' => 'evt_1', 'type' => 'payment.succeeded', 'payment' => ['reference' => 'PAY-1', 'amount' => 50000]])
->assertOk();
expect(WebhookCall::count())->toBe(1);
Queue::assertPushedOn('webhooks', ProsesWebhook::class);
});
it('menolak tanda tangan salah', function () {
kirimWebhook(['event_id' => 'evt_2'], secret: 'salah')->assertUnauthorized();
expect(WebhookCall::count())->toBe(0);
});
it('menolak pesan lama (replay)', function () {
kirimWebhook(['event_id' => 'evt_3'], timestamp: time() - 3600)->assertUnauthorized();
});
it('idempoten untuk event yang sama', function () {
Queue::fake();
$payload = ['event_id' => 'evt_4', 'type' => 'payment.succeeded', 'payment' => ['reference' => 'PAY-4', 'amount' => 50000]];
kirimWebhook($payload)->assertOk();
kirimWebhook($payload)->assertOk();
expect(WebhookCall::count())->toBe(1);
Queue::assertPushed(ProsesWebhook::class, 1);
});
it('tidak menurunkan status pembayaran yang sudah berhasil', function () {
$p = Pembayaran::factory()->create(['referensi' => 'PAY-5', 'jumlah' => 50000, 'status' => 'berhasil']);
kirimWebhook(['event_id' => 'evt_5', 'type' => 'payment.expired', 'payment' => ['reference' => 'PAY-5', 'amount' => 50000]]);
// QUEUE_CONNECTION=sync di phpunit.xml: job langsung dijalankan
expect($p->fresh()->status)->toBe('berhasil');
});
it('menolak jumlah yang tidak cocok', function () {
Pembayaran::factory()->create(['referensi' => 'PAY-6', 'jumlah' => 50000, 'status' => 'menunggu']);
kirimWebhook(['event_id' => 'evt_6', 'type' => 'payment.succeeded', 'payment' => ['reference' => 'PAY-6', 'amount' => 5000]]);
expect(WebhookCall::firstWhere('event_id', 'evt_6')->status)->not->toBe('diproses');
});
Untuk menguji dengan penyedia sungguhan di lingkungan lokal, gunakan fitur "kirim webhook uji" dari dasbor penyedia dan tunnel HTTPS (misalnya Cloudflare Tunnel atau ngrok) ke mesin development. Jangan pernah mengarahkan webhook production ke mesin lokal.
| Error / Gejala | Penyebab | Solusi |
|---|---|---|
| Semua webhook 401 | Secret salah, atau HMAC dihitung dari data hasil parsing | Gunakan getContent(); cocokkan secret per lingkungan (sandbox vs production) |
| 401 hanya sesekali | Jam server tidak sinkron | Aktifkan NTP (timedatectl set-ntp true); tinjau toleransi timestamp |
419 Page Expired |
Route berada di grup web |
Pindahkan ke grup api atau kecualikan dari CSRF |
| Penyedia terus mengirim ulang | Respons lambat atau bukan 2xx | Simpan lalu dispatch job; balas 200 segera |
| Data diproses dua kali | Pemeriksaan duplikat tanpa indeks unik | Indeks unik (penyedia, event_id) + tangkap pelanggaran unik |
| Status final tertimpa | Event datang tidak berurutan | Mesin status hanya maju; abaikan event yang menurunkan status |
Webhook macet di status diterima |
Worker antrean webhooks tidak berjalan |
Jalankan queue:work --queue=webhooks,default |
$request->ip() selalu IP proxy |
Proxy belum dipercaya | Atur trustProxies; jangan andalkan allowlist IP tanpa ini |
| Penyedia tidak bisa menjangkau URL | URL lokal, HTTP, atau di balik login/VPN | Gunakan URL HTTPS publik; route tanpa middleware auth |
Keamanan
hash_equals(), ditambah pemeriksaan timestamp..env, dukung rotasi dengan secret lama sementara.Performa
Maintainability
| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| MySQL | 8.4 LTS |
| Redis | 7.x |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |
Sebelumnya
Cara Mengintegrasikan Laravel dengan API Eksternal Menggunakan HTTP Client
Berikutnya
Panduan Integrasi Payment Gateway di Laravel: Alur Pembayaran, Callback, dan Verifikasi Status
Dokumen ini menjelaskan prosedur konfigurasi autentikasi SSH Key antara server Ubuntu dan GitHub untuk memungkinkan server melakukan operasi Git, seperti clone, pull, dan fetch tanpa menggunakan username dan password akun GitHub.
Peta jalan arsitektur dari satu server hingga banyak server: tahapan pertumbuhan dan sinyal kapan naik tahap, prinsip yang sebaiknya diterapkan sejak awal (stateless, asinkron, data ber-tenant), read replica, pengelolaan data yang terus tumbuh, degradasi yang anggun saat layanan bermasalah, feature...
Menyiapkan lingkungan uji yang jujur, mengukur satu endpoint dengan ApacheBench, mensimulasikan perilaku pengguna sungguhan dengan k6 (skenario, threshold, autentikasi token), menelusuri penyebab request lambat dengan Telescope, memantau server selama pengujian, serta menulis laporan hasil dan angga...
Bagaimana Octane membuat Laravel lebih cepat dengan mem-boot aplikasi sekali dan menyimpannya di memori, apa yang sebenarnya dipercepat (dan yang tidak), risiko kebocoran state antar-request yang wajib dipahami, cara memeriksa kode agar aman untuk Octane, pemasangan dengan FrankenPHP di production,...
03 Nov 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
HijrahKreativa
Kami balas secepatnya
Masuk dulu untuk chat dengan tim kami. Riwayat chat Anda tersimpan di akun.
Masuk