Symfony: Receiving Incoming Webhooks and Verifying HMAC Signatures

1. Why a Dedicated Controller for Webhook Endpoints Is Needed

A webhook endpoint differs fundamentally from a regular API endpoint called by a logged-in user or an authenticated API application. The external service, such as a payment provider or a shipping service, sends the request without a classic session or bearer token, and instead cryptographically signs the payload and places the signature in a dedicated HTTP header. A dedicated controller per webhook source, rather than a generic endpoint shared across multiple providers, has the advantage that each provider's signature header, secret, and processing logic stay clearly separated and can be tested and maintained independently of one another.

It also matters that a webhook controller absolutely must be excluded from the application's regular firewall configuration, because the endpoint naturally cannot carry a Symfony session or CSRF token the way a normal, browser-based endpoint would expect. Instead, the HMAC signature fully replaces those mechanisms as proof of authenticity and integrity, which is why the security of the entire endpoint depends directly and exclusively on the correctness of that signature check.

2. A Dedicated Controller for Webhook Endpoints in Practice

The example below shows a controller for a GitHub-style webhook that reads the signature from the X-Hub-Signature-256 header and compares it against a self-computed HMAC-SHA256 signature of the raw request body. What matters most is that the signature calculation uses exclusively the unmodified, raw body via getContent(), because even a minimal deviation, such as an extra whitespace character or a different field order after re-encoding to JSON, would change the computed signature and cause verification to fail incorrectly.

The injected webhookSecret ideally comes from the secrets vault or an environment variable, never from plaintext code, because anyone who knows that secret can attach a valid signature to an arbitrary, forged payload. On a signature mismatch, the controller deliberately returns only a generic 401 response without details about the reason for failure, so as not to hand an attacker information that could make guessing the secret easier, while still logging the incident server-side for its own traceability.

<?php

declare(strict_types=1);

namespace App\Controller\Webhook;

use Psr\Log\LoggerInterface;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class GithubWebhookController
{
    public function __construct(
        private readonly string $webhookSecret,
        private readonly LoggerInterface $logger,
    ) {
    }

    #[Route('/webhooks/github', methods: ['POST'])]
    public function __invoke(Request $request): Response
    {
        $payload = $request->getContent();
        $signatureHeader = $request->headers->get('X-Hub-Signature-256', '');

        $expected = 'sha256=' . hash_hmac('sha256', $payload, $this->webhookSecret);

        if (!hash_equals($expected, $signatureHeader)) {
            $this->logger->warning('Webhook signature mismatch.');

            return new JsonResponse(['error' => 'invalid signature'], Response::HTTP_UNAUTHORIZED);
        }

        // ... the verified payload is processed here, including an idempotency check

        return new JsonResponse(['status' => 'accepted'], Response::HTTP_ACCEPTED);
    }
}

3. hash_hmac() and hash_equals() Against Timing Attacks

hash_hmac() computes a cryptographic hash from a payload and a secret key that is practically impossible to forge without knowing the key, because even a minimal change to the payload leads to a completely different hash value. What matters, though, is not just the computation but also how the two hash values are compared: a naive comparison using the === operator or the strcmp() function stops at the first differing byte in most PHP implementations, which theoretically lets an attacker guess the correct hash value byte by byte through tiny timing differences in the response, a classic timing attack.

hash_equals(), by contrast, always compares the full length of both strings in constant time, regardless of where a difference occurs, making it worthless for an attacker to measure timing differences. This function was introduced in PHP specifically for this use case and should be used for every security-relevant string comparison, not just HMAC signatures, but also, for example, comparing API keys or session tokens. A common, subtle mistake is mixing up the parameter order of hash_equals(): the first parameter should always be the known, trusted value, and the second should be the value supplied by the user or external service.

4. The Symfony Webhook Component Compared to a Custom Implementation

Symfony has offered its own webhook component for a few versions now, tightly integrated with the RemoteEvent system and the mailer and notifier bridges, primarily designed for pre-built integrations such as Mailgun, Postmark, or Mailjet bounce notifications. For that purpose, the component provides a generic WebhookController that forwards incoming requests to a registered RequestParser, which in turn encapsulates signature verification for that specific provider and produces a RemoteEvent object, which can then be processed further through the Symfony Messenger.

For generic, self-defined webhooks from third parties like Stripe, GitHub, or a custom internal microservice, though, this mechanism is often not the best fit in practice, because it is tightly tailored to the RemoteEvent concept and requires a dedicated RequestParser for every new provider, which does not necessarily save on the flexibility a custom controller already offers. Most projects therefore fare better with a lean, custom controller like the one in the example above, tailored directly to their own domain logic, while the Symfony webhook component makes the most sense when a mailer or notifier bridge with a pre-built RequestParser for that specific provider already exists anyway.

5. Idempotency for Repeated Webhook Deliveries

Nearly every webhook provider only guarantees at-least-once delivery, not exactly-once, which means the same event can be sent to the same endpoint multiple times due to a network error, a delayed response timeout, or the provider's own internal retry logic. If your own code fully reprocesses an event on every delivery, that can lead to duplicately booked payments, duplicately sent notifications, or inconsistent database state, depending on which business action the webhook event triggers.

The robust solution is to identify every event by a unique event id supplied by the provider, store that id in a dedicated database table with a UNIQUE constraint, and only run the actual processing step if inserting that id actually succeeds. If the insert fails due to a constraint violation, the event has already been processed, and the controller can immediately respond with the original success status without running the business logic a second time. This approach is more robust than a simple cache-based deduplication mechanism, because a database constraint reliably guarantees only a single processing run even under concurrent, parallel deliveries of the same event.

6. Tying the Idempotency Check Transactionally to the Actual Processing

A common, subtle mistake is storing the event id but then running the actual business processing as a separate, non-transactional step afterward. If the business processing fails after the event id has already been stored successfully, a later, legitimate retry from the provider gets incorrectly recognized as a duplicate and ignored, even though the event was never successfully processed. The correct solution is to run the event id insert and the actual business processing within the same database transaction, so that either both commit together or, on failure, both roll back together.

In Symfony, a good fit for this is a dedicated EntityManager transaction block, in which the event id is stored first via persist() and flush(), followed by the actual business logic within the same transaction. Alternatively, especially for compute-intensive or long-running processing, it is worth splitting this via the Symfony Messenger: the webhook controller only stores the event id transactionally and then dispatches an asynchronous message handler that takes over the actual, potentially slower processing, while the controller itself responds quickly with status code 202 Accepted, which many webhook providers expect anyway as the timeout boundary for the response.

7. Common Mistakes in Signature Verification in Practice

A particularly common mistake happens when a Symfony event listener or a global body parser already consumes the request body before the webhook controller runs, or decodes it as JSON and then re-encodes it, because the body used for signature verification no longer matches the original body sent by the provider byte for byte. For that reason, a webhook controller should call getContent() as early as possible, before any other middleware or kernel listener has had a chance to manipulate the request body, and when in doubt, explicitly exclude the affected endpoint from generic body-parsing listeners.

A second common mistake is sharing the same secret value across every webhook source instead of using an independent secret per provider, which means a compromise of a single provider's secret immediately endangers the other endpoints as well. A third mistake is the absence of an explicit timeout or size limit for the webhook payload, because an attacker who cannot forge a valid signature but knows the URL can still try to burden the endpoint with oversized or deliberately slowly sent requests, which is why a reasonable body size limit at the web server or Symfony configuration level remains worthwhile even when the signature check itself is implemented correctly.

8. Testing Webhook Endpoints Automatically

A webhook controller tests excellently with a WebTestCase, where the test itself computes a valid HMAC signature using the same algorithm and the same secret configured in the test environment and sends it along as a header. This covers both the success case with a correct signature and the failure case with a deliberately wrong or missing signature, where the failure case should explicitly check for the expected 401 status code and the absence of any business processing.

For the idempotency mechanism, a dedicated test is worthwhile, sending the same request payload and the same event id to the endpoint twice in a row and verifying that the business processing, such as a database insert or a sent email, actually happens only once. Such a test covers exactly the race condition and duplicate scenarios that are hardest to reproduce manually in practice, because they depend on the actual delivery logic of the external provider and can only be simulated locally, not genuinely reproduced.

9. A Checklist for Production-Ready Webhook Endpoints

A production-ready webhook endpoint should satisfy at least the following points: a dedicated controller per provider, sitting outside the regular session-based firewall configuration, a signature check using hash_hmac() and hash_equals() against the unmodified raw body, a per-provider individual secret from the secrets vault rather than plaintext code, an idempotency check tied transactionally to the business processing via a unique event id, and a reasonable body size limit against abuse.

It is also worth structurally logging every incoming webhook, regardless of whether signature verification succeeds, so that in case of a failure it stays traceable whether a provider actually sent a faulty signature or whether it was a genuine attack attempt. Anyone who accounts for these points from the start avoids the most common production problems around webhooks, which typically only surface once a provider unexpectedly retries, a secret gets rotated, or an attacker deliberately tries to abuse the endpoint.

10. Summary

11. FAQ: Webhook Reception and HMAC Verification: The Essentials at a Glance