Your first webhook

This guide creates a basic webhook endpoint that receives a payment event and sends it to a handler class.

Create a provider

A provider tells RelayKit how to verify a request and identify the event name.

namespace App\Webhooks\Providers;

use RelayKit\Providers\Provider;
use RelayKit\Requests\IncomingWebhook;

class PaymentProvider extends Provider
{
    public function eventName(IncomingWebhook $webhook): string
    {
        return $webhook->payload('type');
    }
}

Register the provider

Add the provider to config/relaykit.php.

'providers' => [
    'payments' => App\Webhooks\Providers\PaymentProvider::class,
],

Create a handler

Handlers contain your application logic.

namespace App\Webhooks\Handlers;

use RelayKit\Contracts\WebhookHandler;
use RelayKit\Events\WebhookEvent;

class PaymentSucceededHandler implements WebhookHandler
{
    public function handle(WebhookEvent $event): void
    {
        $customerId = $event->data('customer_id');

        // Update the customer account here.
    }
}

Map the event

'events' => [
    'payments.payment_succeeded' => App\Webhooks\Handlers\PaymentSucceededHandler::class,
],

Test the endpoint

curl -X POST https://example.test/webhooks/payments \
    -H "Content-Type: application/json" \
    -H "X-RelayKit-Signature: test-signature" \
    -d '{"type":"payment_succeeded","customer_id":"cus_123"}'

RelayKit will verify the request, create a delivery record, and dispatch the handler.