Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / REST API, Integrasi & Automation / Webhook Laravel: Cara Menerima...
REST API, Integrasi & Automation

Webhook Laravel: Cara Menerima, Memvalidasi, dan Memproses Event dari Sistem Eksternal

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
14 min read
14 views

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.

Overview

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)

Prerequisites

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)

Step-by-step Tutorial

Langkah 1: Pelajari Kontrak Webhook Penyedia

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.

Langkah 2: Tabel Penyimpanan Webhook

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.

Langkah 3: Konfigurasi Penyedia

// 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'))),
        ],
    ],
];

Langkah 4: Verifikasi Tanda Tangan

// 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:

  1. Hitung HMAC dari body mentah (getContent()). Mengubah urutan field atau spasi lewat json_encode($request->all()) menghasilkan hash yang berbeda.
  2. Gunakan hash_equals(), bukan ===. Perbandingan biasa bisa membocorkan informasi lewat perbedaan waktu eksekusi.
  3. Periksa timestamp agar request sah yang pernah ditangkap tidak bisa dikirim ulang berhari-hari kemudian. Timestamp ikut ditandatangani, sehingga tidak bisa diganti oleh penyerang.

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.

Langkah 5: Controller Penerima

// 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.

Langkah 6: Job Pemroses

// 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.

Langkah 7: Handler per Jenis Event

// 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:

  • Mesin status hanya bergerak maju. Status final (berhasil, dikembalikan) tidak boleh ditimpa oleh event yang datang terlambat.
  • Kunci baris (lockForUpdate) agar dua event untuk pembayaran yang sama tidak diproses bersamaan.
  • Validasi silang jumlah dan referensi dengan data milik Anda. Tanda tangan membuktikan pengirimnya, validasi silang membuktikan isinya cocok dengan transaksi Anda.
  • Event tidak dikenal diabaikan dan dicatat, bukan dijadikan error, sehingga tidak memicu retry tanpa akhir.
  • Untuk penyedia yang menyediakan API cek status, pertimbangkan memverifikasi ulang status lewat API sebelum menandai pembayaran berhasil (lihat artikel Payment Gateway).

Langkah 8: Pemrosesan Ulang dan Pemantauan

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.

Langkah 9: Alternatif dengan Paket

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.

Langkah 10: Test

// 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.

Troubleshooting

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

Best Practices

Keamanan

  • Verifikasi tanda tangan dari body mentah dengan hash_equals(), ditambah pemeriksaan timestamp.
  • Validasi silang isi event (referensi, jumlah) dengan data milik Anda.
  • Allowlist IP hanya sebagai lapisan tambahan, bukan pengganti tanda tangan.
  • Simpan secret di .env, dukung rotasi dengan secret lama sementara.
  • Catat percobaan dengan tanda tangan tidak valid di log keamanan.

Performa

  • Endpoint hanya memverifikasi, menyimpan, dan men-dispatch; pemrosesan di queue khusus.
  • Indeks unik untuk idempotensi, bukan query pemeriksaan.
  • Prune data webhook lama secara berkala.

Maintainability

  • Satu controller dan job generik; handler per penyedia.
  • Payload mentah tersimpan untuk investigasi dan pemrosesan ulang.
  • Perintah proses ulang dan pemantauan webhook gagal/macet.
  • Test untuk tanda tangan, replay, duplikat, urutan, dan validasi silang.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
MySQL 8.4 LTS
Redis 7.x
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya