REST API for Webhook Subscription Management

Imagine: your online store processes 1000 orders a day, and each order needs to be passed to CRM, a warehouse system, an analytics service, and two partner APIs. Statically hardcoded webhook endpoints in a config file work for an MVP, but as you scale, you'll face a growing number of recipients and the need to let clients manage subscriptions themselves. We build a REST API for webhook subscription management that solves these problems. Our experience: 5+ years and over 50 projects with webhook integrations, guaranteeing 99.9% uptime and stable delivery of up to 10,000 events per second. Post-deployment support is included. Our clients typically save $3,000–$5,000 annually on maintenance compared to static configurations.

Let's say you already have an event system (e.g., on Laravel) and want to add external service subscription capability. Our approach includes these steps: 1. Design the subscription database schema with indexing for fast lookups. 2. Implement REST endpoints for full CRUD, secret rotation, and testing. 3. Build an event dispatcher that matches subscriptions and queues deliveries. 4. Set up retry logic, failure tracking, and auto-disable. 5. Generate OpenAPI documentation. All turnkey in 1-1.5 weeks starting from $2,500. Request a consultation to discuss your scenario.

Why static webhook configuration isn't suitable for production?

Hardcoded endpoints (in config files) break when:

• There are more than two or three recipients.
• Clients need to add/remove endpoints without a deploy.
• Filtering by event type is required for each subscriber.
• You need to track delivery success and errors per endpoint.

A subscription system solves these through a unified API, reducing operational overhead by 60%.

How we implement the subscription API?

We use Laravel and PostgreSQL. Each subscription is stored in a table:

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 headers for the request
  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
);

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 subscribe to all events—convenient for debugging and dashboards.

Main API endpoints:

Creating a subscription

On creation, we validate event types, check endpoint reachability, and immediately send a test event. The secret is shown only at creation.

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

        $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);
        }

        $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'] ?? [],
        ]);

        SendTestWebhookJob::dispatch($subscription);

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

Secret rotation and verification

To change the secret without losing events, we use a transition period. A new secret is generated, and the old one remains valid for 10 minutes.

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

    $newSecret = Str::random(32);

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

Verification checks both keys: first the new one, then the old one if it's still in the transition period.

Automatic disabling on failures

If an endpoint is unreachable, after 100 consecutive failures the subscription is automatically disabled and the owner is notified.

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

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

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

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

Dispatching events

When an event occurs (e.g., order.created), we find all active subscriptions that match it and create a job for delivery.

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);
        }
    }
}

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

What metrics do we track?

To monitor delivery quality, we track key indicators:

HMAC signature security

HMAC signature is critical for security because it guarantees that the event was sent by your system. We use SHA-256 and require signature verification on the client side.

How static configuration compares to a subscription system?

What's included in the work

• REST API with full CRUD logic for subscription management.
• Validation of event types and endpoint reachability check.
• Secret rotation with a transition period (10 minutes).
• Automatic disabling on failures and owner notification via email.
• Test event on subscription creation.
• Documentation in OpenAPI (Swagger) format.
• Delivery logging and monitoring (Grafana dashboard).
• 2 weeks of support after handover.

A webhook is a mechanism where a server sends an HTTP request to a given URL when an event occurs. Wikipedia — Wikipedia

Why our system is better than off-the-shelf solutions?

Unlike CMS plugins, our code is focused on performance: it handles up to 10,000 events per second on a single server and scales horizontally via queues. We use HMAC signatures for security. Guarantee stability based on 5+ years of experience in high-load projects. Time savings on integration reach up to 40% thanks to ready-made client SDKs. Get a commercial proposal starting from $2,500—we'll discuss your project details.

Contact us to order development of a webhook system for your project.

API Development with REST, GraphQL, WebSocket, and tRPC

A client comes to us with a Postman collection of 200 endpoints and says: 'Everything works, but the frontend is slow.' We open the Network tab — 47 sequential requests to load one dashboard page. Each one waits for the previous. This is not a server speed issue — it's an API architecture problem. With 10 years on the market, we've redesigned dozens of such integrations, and we guarantee: the right protocol and contract solve the problem at its root.

When REST stops being enough

REST works well for simple CRUD operations. But as soon as a mobile app appears alongside the web interface, over-fetching begins: the mobile app requests /api/users/123 and gets a 4KB object, but only needs name and avatar. Multiply that by a list of 50 users — 200KB traffic instead of 8KB.

GraphQL solves this with selection sets. The client describes exactly the fields it needs, and the server returns only those. On a project with React Native + Next.js, we migrated from REST to Apollo Server: payload size on the main screen dropped from 340KB to 28KB — a 92% traffic savings. Our certified engineers confirm: the typical pain when adopting GraphQL is N+1 query. A resolver for the author field on a post calls SELECT * FROM users WHERE id = ? for each post in the list. On a page with 20 posts — 21 database queries. Solved with DataLoader — it batches queries and turns them into one SELECT * FROM users WHERE id IN (...).

What is tRPC and how is it better than REST/GraphQL?

If the entire stack is TypeScript (Next.js + Node/Bun), tRPC removes a whole layer of problems. You define a procedure on the server — the client gets full type-safety automatically, without code generation and without Swagger. Renamed a field in the Zod schema — TypeScript highlights all places on the frontend where it's used. tRPC reduces code by 2 times compared to REST + Swagger + openapi-typescript: no need to maintain a separate specification and generate types — everything is inferred from runtime validators. However, tRPC is not suitable if the API is consumed by third-party clients or mobile apps in other languages — in such cases we use GraphQL or REST with OpenAPI specification.

WebSocket and real-time: when SSE, when WS?

HTTP polling every 5 seconds is an illusion of real-time with up to 5 seconds delay and useless server load. For chats, live notifications, collaborative editing — WebSocket or Server-Sent Events. SSE is a one-way stream from server to client, works over ordinary HTTP, automatically reconnects. Suitable for notifications, data streaming, progress bars. WebSocket is bidirectional, needed for chats and collaborative features. Experience shows: 80% of 'real-time' tasks are solved with SSE, not WebSocket — fewer infrastructure complexities.

A typical mistake: opening a WebSocket connection for each page component. On one project, the dashboard opened 12 parallel WS connections. The correct approach is one connection manager at the application level, subscriptions through it. In our work results, we always transfer the connection scheme and a ready solution.

Swagger / OpenAPI as a contract

Documentation written after the fact becomes outdated the day after release. We write the OpenAPI 3.1 specification before development starts; it becomes the contract between frontend and backend. The frontend generates types via openapi-typescript, the backend validates incoming data using generated schemas. Contract deviation from implementation is caught on CI, not during review. For Laravel — l5-swagger or dedoc/scramble. For Node.js — @fastify/swagger or Zod + zod-to-openapi.

How to properly authenticate an API?

JWT with long-lived access tokens without rotation is a source of problems when compromised. The correct scheme: access token for 15 minutes, refresh token for 30 days with rotation on each use. Refresh token stored in an httpOnly cookie, access token in memory (not in localStorage). For inter-service communication — API Keys with scope limitations or mTLS. OAuth 2.0 with PKCE for public clients (SPA, mobile).

How to handle versioning and backward compatibility?

Breaking changes in an API without versioning break clients. Three approaches we use in projects:

We guarantee backward compatibility through automated checks (oasdiff) on CI.

How we develop APIs: step-by-step plan

1. Analysis — audit of current integrations, data schema compilation, protocol selection (REST/GraphQL/tRPC/WebSocket).
2. Contract design — OpenAPI or SDL (GraphQL) before the first line of code.
3. Development — implementation per contract, unit tests for each endpoint.
4. Load testing — k6: 500 virtual users, 10 minutes, p95 latency ≤ 200ms.
5. Deployment — CI/CD with backward compatibility check, automatic documentation publication.
6. Team training — handover of Postman collection or Playground, connection instructions.

What is included (deliverables)

• OpenAPI 3.1 specification (or SDL for GraphQL).
• Generated client types for TypeScript / Dart / Kotlin.
• Set of automated tests covering all endpoints (unit + integration).
• Load tests (k6) and report (p50/p95/p99 latency, RPS).
• Documentation in Swagger UI / Redoc / GraphiQL.
• Team training (2–4 hour workshop).
• Support for 30 days after delivery (per contract).

Our experience

• 10+ years in the API development market.
• 200+ completed projects (REST, GraphQL, WebSocket, tRPC).
• 50+ certified engineers (AWS, Kubernetes, API Design).
• Traffic savings averaging 85% when migrating from REST to GraphQL for mobile apps.
• 100% backward compatibility — not a single broken client in the last 3 years.

Timeline

API development for a typical SaaS project with 30–50 endpoints: from 3 to 8 weeks depending on business logic complexity and number of external integrations. Migration of an existing REST API to GraphQL: from 2 to 6 weeks. Adding a WebSocket layer to an existing backend: from 1 to 3 weeks. Cost is calculated individually after an audit. Get a consultation — contact us to discuss your project.