Webhook system with subscription management subscribe unsubscribe

Setting Up Webhook System with Subscription Management (Subscribe/Unsubscribe)

Statically hardcoded webhook endpoints in config is an MVP solution. Once you have more than two recipients or need to let clients register their own endpoints, you need an API-based subscription management system.

Subscription Model

Each subscription connects three things: consumer (who receives), events (what they receive), and endpoint (where to send).

CREATE TABLE webhook_subscriptions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  consumer_id UUID NOT NULL REFERENCES consumers(id),
  endpoint_url TEXT NOT NULL,
  secret TEXT NOT NULL,            -- hmac secret for verification
  description TEXT,
  events TEXT[] NOT NULL,          -- ['order.created', 'order.updated', '*']
  is_active BOOLEAN DEFAULT true,
  headers JSONB DEFAULT '{}',      -- additional request headers
  timeout_seconds INTEGER DEFAULT 10,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  last_delivery_at TIMESTAMPTZ,
  failure_count INTEGER DEFAULT 0, -- counter of consecutive failures
  disabled_at TIMESTAMPTZ          -- NULL = active
);

-- Registry of allowed event types
CREATE TABLE webhook_event_types (
  name TEXT PRIMARY KEY,           -- 'order.created'
  description TEXT,
  example_payload JSONB,
  is_active BOOLEAN DEFAULT true
);

The * pattern in events means subscription to all events—convenient for debugging and dashboards.

Subscription Management API

POST   /webhooks/subscriptions          — create subscription
GET    /webhooks/subscriptions          — list consumer subscriptions
GET    /webhooks/subscriptions/{id}     — subscription details
PATCH  /webhooks/subscriptions/{id}     — update (URL, events, activity)
DELETE /webhooks/subscriptions/{id}     — delete subscription
POST   /webhooks/subscriptions/{id}/test — send test event
GET    /webhooks/event-types            — list available event types

Creating a Subscription

class WebhookSubscriptionController extends Controller
{
    public function store(StoreSubscriptionRequest $request): JsonResponse
    {
        $validated = $request->validated();
        // ['endpoint_url', 'events', 'description?', 'headers?']

        // Validate events
        $invalidEvents = array_diff(
            array_filter($validated['events'], fn($e) => $e !== '*'),
            WebhookEventType::where('is_active', true)->pluck('name')->toArray()
        );

        if (!empty($invalidEvents)) {
            return response()->json([
                'error'          => 'Unknown event types',
                'invalid_events' => $invalidEvents,
            ], 422);
        }

        // Check endpoint reachability (optional)
        $reachable = $this->probeEndpoint($validated['endpoint_url']);

        $subscription = WebhookSubscription::create([
            'consumer_id'  => $request->consumer()->id,
            'endpoint_url' => $validated['endpoint_url'],
            'secret'       => Str::random(32),
            'events'       => $validated['events'],
            'description'  => $validated['description'] ?? null,
            'headers'      => $validated['headers'] ?? [],
        ]);

        // Send test event on creation
        SendTestWebhookJob::dispatch($subscription);

        return response()->json([
            'id'           => $subscription->id,
            'endpoint_url' => $subscription->endpoint_url,
            'events'       => $subscription->events,
            'secret'       => $subscription->secret, // only shown on creation
            'created_at'   => $subscription->created_at,
            'test_sent'    => true,
        ], 201);
    }

The secret is shown to the client only on creation. After that, only through key rotation.

Secret Rotation

public function rotateSecret(WebhookSubscription $subscription): JsonResponse
{
    $this->authorize('update', $subscription);

    $newSecret = Str::random(32);

    // Transition period: accept both secrets for 10 minutes
    $subscription->update([
        'secret_old'            => $subscription->secret,
        'secret'                => $newSecret,
        'secret_rotated_at'     => now(),
    ]);

    return response()->json([
        'secret'      => $newSecret,
        'valid_until' => now()->addMinutes(10)->toIso8601String(),
        'note'        => 'Old secret valid for 10 minutes during rotation',
    ]);
}

Signature verification with transition period support:

public function verifySignature(Request $request, WebhookSubscription $sub): bool
{
    $body      = $request->getContent();
    $signature = $request->header('X-Webhook-Signature');
    $expected  = 'sha256=' . hash_hmac('sha256', $body, $sub->secret);

    if (hash_equals($expected, $signature ?? '')) {
        return true;
    }

    // Check old secret during transition period
    if ($sub->secret_old && $sub->secret_rotated_at?->gt(now()->subMinutes(10))) {
        $expectedOld = 'sha256=' . hash_hmac('sha256', $body, $sub->secret_old);
        return hash_equals($expectedOld, $signature ?? '');
    }

    return false;
}

Auto-Disable on Failures

If an endpoint is unreachable for several days, it makes no sense to keep trying and accumulate queue:

class WebhookFailureTracker
{
    public function recordFailure(WebhookSubscription $subscription): void
    {
        $subscription->increment('failure_count');

        // Disable after 100 consecutive failures
        if ($subscription->failure_count >= 100 && $subscription->is_active) {
            $subscription->update([
                'is_active'   => false,
                'disabled_at' => now(),
            ]);

            // Notify subscription owner
            Notification::send(
                $subscription->consumer,
                new WebhookSubscriptionDisabled($subscription)
            );
        }
    }

    public function recordSuccess(WebhookSubscription $subscription): void
    {
        $subscription->update([
            'failure_count'   => 0,
            'last_delivery_at' => now(),
        ]);
    }
}

Test Event

On creation and on demand—send webhook.test:

class SendTestWebhookJob implements ShouldQueue
{
    public function handle(): void
    {
        $payload = [
            'event'     => 'webhook.test',
            'id'        => Str::uuid(),
            'timestamp' => now()->toIso8601String(),
            'data'      => [
                'subscription_id' => $this->subscription->id,
                'message'         => 'This is a test event. Your webhook is configured correctly.',
            ],
        ];

        Http::timeout(10)
            ->withHeaders($this->buildHeaders($payload))
            ->post($this->subscription->endpoint_url, $payload);
    }
}

Dispatch Event to All Matching Subscriptions

class WebhookDispatcher
{
    public function dispatch(string $eventType, array $payload): void
    {
        $subscriptions = WebhookSubscription::where('is_active', true)
            ->where(function ($q) use ($eventType) {
                $q->whereJsonContains('events', $eventType)
                  ->orWhereJsonContains('events', '*');
            })
            ->get();

        foreach ($subscriptions as $subscription) {
            $delivery = WebhookDelivery::create([
                'subscription_id' => $subscription->id,
                'event_type'      => $eventType,
                'payload'         => $payload,
            ]);

            SendWebhookJob::dispatch($delivery);
        }
    }
}

// Usage after order creation:
app(WebhookDispatcher::class)->dispatch('order.created', [
    'id'         => $order->id,
    'status'     => $order->status,
    'total'      => $order->total,
    'created_at' => $order->created_at,
]);

Timelines

Subscription management API with basic logic: 3–4 days. With secret rotation, auto-disable, test events, and full API documentation: 1–1.5 weeks.