relay webhook signature verification

backend/.env

@@ -68,6 +68,9 @@ DATABASE_URL=""
 RELAY_URL=https://relay.hyvor.com
 # API key with scopes: `sends.send`, `domains.read`, `domains.write`
 RELAY_API_KEY=
+# Secret used to sign the webhook payloads.
+RELAY_WEBHOOK_SECRET=
+
 # Maximum number of emails that can be sent per second.
 # This is the rate limit of the Hyvor Relay project.
 # Default is 10 in Relay, we set it to 8 here.

backend/.env.test

@@ -27,6 +27,7 @@ FILESYSTEM_ADAPTER=local
 #RELAY_API_KEY=test-relay-key
 RELAY_URL=https://relay.hyvor.com
 RELAY_API_KEY=test-relay-key
+RELAY_WEBHOOK_SECRET=test-relay-webhook-secret
 
 NOTIFICATION_MAIL_FROM_ADDRESS=from@example.com
 NOTIFICATION_MAIL_FROM_NAME='Hyvor Post'

backend/src/Api/Public/Controller/Integration/Relay/RelayWebhookController.php

@@ -6,13 +6,15 @@
 use App\Entity\Type\SendStatus;
 use App\Service\Domain\DomainService;
 use App\Service\Domain\Dto\UpdateDomainDto;
+use App\Service\AppConfig;
 use App\Service\Issue\Dto\UpdateSendDto;
 use App\Service\Issue\SendService;
 use App\Service\Subscriber\SubscriberService;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+use Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException;
 use Symfony\Component\Routing\Attribute\Route;
 
 /**
@@ -37,6 +39,7 @@
 class RelayWebhookController extends AbstractController
 {
     public function __construct(
+        private AppConfig         $appConfig,
         private DomainService     $domainService,
         private SubscriberService $subscriberService,
         private SendService       $sendService,
@@ -48,15 +51,24 @@ public function __construct(
     public function handleWebhook(Request $request): JsonResponse
     {
         $content = $request->getContent();
+
+        $signature = $request->headers->get('X-Signature');
+        if ($signature === null) {
+            throw new UnauthorizedHttpException('', 'Missing webhook signature');
+        }
+
+        $expected = hash_hmac('sha256', $content, $this->appConfig->getRelayWebhookSecret());
+        if (!hash_equals($expected, $signature)) {
+            throw new UnauthorizedHttpException('', 'Invalid webhook signature');
+        }
+
         /** @var array{
          *     'event': string,
          *     'payload': array<string, mixed>
          *  } $data
          */
         $data = json_decode($content, true);
 
-        // TODO: Validate the webhook
-
         $event = $data['event'];
         $payload = $data['payload'];
 

backend/src/Service/AppConfig.php

@@ -20,6 +20,9 @@ public function __construct(
         #[Autowire('%env(string:RELAY_API_KEY)%')]
         private string $relayApiKey,
 
+        #[Autowire('%env(string:RELAY_WEBHOOK_SECRET)%')]
+        private string $relayWebhookSecret,
+
         // Email configuration
         #[Autowire('%env(int:MAX_EMAILS_PER_SECOND)%')]
         private int    $maxEmailsPerSecond,
@@ -94,5 +97,9 @@ public function getNotificationRelayApiKey(): string
         return $this->notificationRelayApiKey ?: $this->relayApiKey;
     }
 
+    public function getRelayWebhookSecret(): string
+    {
+        return $this->relayWebhookSecret;
+    }
 
 }

backend/tests/Api/Public/Integration/Relay/RelayWebhookTest.php

@@ -13,16 +13,24 @@
 
 class RelayWebhookTest extends WebTestCase
 {
+    private const WEBHOOK_SECRET = 'test-relay-webhook-secret';
+
     /**
      * @param array<string, mixed> $data
+     * @param array<string, string> $headers
      */
-    private function callWebhook(array $data): Response
+    private function callWebhook(array $data, array $headers = []): Response
     {
+        if (!isset($headers['X-Signature'])) {
+            $body = json_encode($data, JSON_THROW_ON_ERROR);
+            $headers['X-Signature'] = hash_hmac('sha256', $body, self::WEBHOOK_SECRET);
+        }
 
         return $this->publicApi(
             'POST',
             '/integration/relay/webhook',
-            $data
+            $data,
+            $headers,
         );
     }
 
@@ -373,4 +381,44 @@ public function test_ignore_webhooks_for_emails_without_send_id(): void
         $response = $this->callWebhook($data);
         $this->assertSame(200, $response->getStatusCode());
     }
+
+    public function test_webhook_rejected_when_signature_missing(): void
+    {
+        $data = [
+            "event" => "send.recipient.accepted",
+            "payload" => [
+                "send" => [
+                    "headers" => []
+                ],
+                "attempt" => [
+                    "created_at" => 1758221942
+                ]
+            ]
+        ];
+
+        $response = $this->publicApi(
+            'POST',
+            '/integration/relay/webhook',
+            $data,
+        );
+        $this->assertSame(401, $response->getStatusCode());
+    }
+
+    public function test_webhook_rejected_when_signature_invalid(): void
+    {
+        $data = [
+            "event" => "send.recipient.accepted",
+            "payload" => [
+                "send" => [
+                    "headers" => []
+                ],
+                "attempt" => [
+                    "created_at" => 1758221942
+                ]
+            ]
+        ];
+
+        $response = $this->callWebhook($data, ['X-Signature' => 'invalid-signature']);
+        $this->assertSame(401, $response->getStatusCode());
+    }
 }