Add support for optional timestamp header in webhooks

README.md

@@ -66,6 +66,11 @@ return [
      * This is the name of the header where the signature will be added.
      */
     'signature_header_name' => 'Signature',
+
+    /*
+     * This is the name of the header where the timestamp will be added.
+     */
+    'timestamp_header_name' => 'Timestamp',
 
     /*
      * These are the headers that will be added to all webhook requests.
@@ -219,6 +224,21 @@ WebhookCall::create()
 
 If you want to customize the name of the header, you don't need to use a custom signer, but you can change the value in the `signature_header_name` in the `webhook-server` config file.
 
+### Use Timestamp
+
+This is highly recommended to help prevent replay attacks.
+
+Timestamping is disabled by default, but you can enable it by calling `useTimestamp()` method.
+
+```php
+WebhookCall::create()
+    ->useTimestamp()
+    ...
+    ->dispatch();
+```
+
+By calling this method, the `Timestamp` header will be set.
+
 ### Retrying failed webhooks
 
 When the app to which we're sending the webhook fails to send a response with a `2xx` status code the package will consider the call as failed. The call will also be considered failed if the remote app doesn't respond within 3 seconds.

config/webhook-server.php

@@ -36,6 +36,11 @@
      */
     'signature_header_name' => 'Signature',
 
+    /*
+     * This is the name of the header where the timestamp will be added.
+     */
+    'timestamp_header_name' => 'Timestamp',
+
     /*
      * These are the headers that will be added to all webhook requests.
      */

src/CallWebhookJob.php

@@ -50,6 +50,8 @@ class CallWebhookJob implements ShouldQueue
 
     public string|bool $verifySsl;
 
+    public bool $useTimestamp = false;
+
     public bool $throwExceptionOnFailure;
 
     /** @var string|null */
@@ -82,6 +84,10 @@ public function handle()
                 ? ['query' => $this->payload]
                 : ['body' => $this->generateBody()];
 
+            if ($this->useTimestamp) {
+                $this->addTimestampToHeaders();
+            }
+
             $this->response = $this->createRequest($body);
 
             if (! Str::startsWith($this->response->getStatusCode(), 2)) {
@@ -188,6 +194,12 @@ private function generateBody(): string
         };
     }
 
+    private function addTimestampToHeaders(): void
+    {
+        $timestampHeader = config('webhook-server.timestamp_header_name');
+        $this->headers[$timestampHeader] = now()->timestamp;
+    }
+
     public function failed(Throwable $e)
     {
         if ($this->throwExceptionOnFailure) {

src/WebhookCall.php

@@ -226,6 +226,12 @@ public function useJob(string $webhookJobClass): self
         return $this;
     }
 
+    public function useTimestamp(bool $use = true): self
+    {
+        $this->callWebhookJob->useTimestamp = $use;
+        return $this;
+    }
+
     public function dispatch(): PendingDispatch
     {
         $this->prepareForDispatch();

tests/CallWebhookJobTest.php

@@ -402,3 +402,23 @@ function baseGetRequest(array $overrides = []): array
         return true;
     });
 });
+
+
+it('sets the timestamp header when using the timestamp option', function () {
+    baseWebhook()
+        ->useTimestamp()
+        ->dispatch();
+
+    $baseRequest = baseRequest();
+
+    $timestampHeaderName = config('webhook-server.timestamp_header_name');
+
+    $baseRequest['options']['headers'][$timestampHeaderName] = TestTime::now()->getTimestamp();
+
+    artisan('queue:work --once');
+
+    $this
+        ->testClient
+        ->assertRequestsMade([$baseRequest]);
+});
+