Added webhook helpers to the client

README.md

@@ -72,6 +72,33 @@ When you try another request, the request will fail. This client will throw you
 
 We also have an option `$apiClient->enableRetryOnRateLimitHit()` you can use to enable retry's of requests when you hit a rate limit. When the client hits the rate limit, it will sleep for 20 seconds and try the same request again. 
 
+## Webhooks helper
+This client also contains a helper for receiving webhooks, including a signature checker. This is included in the `PicqerWebhook` class.
+
+To receive a webhook, you only need the following:
+
+```php
+<?php
+
+require __DIR__ . '/vendor/autoload.php';
+
+$webhook = Picqer\Api\PicqerWebhook::retrieve();
+
+echo 'Hook received: ' . $webhook->getName() . ' that was triggered at ' . $webhook->getEventTriggeredAt() . PHP_EOL;
+echo $webhook->getData();
+```
+
+We recommend using signature validation to be sure the webhook was sent by Picqer. Create a hook with a secret, then check the signature of the webhook with that secret as follows:
+
+```php
+<?php
+
+require __DIR__ . '/vendor/autoload.php';
+
+$webhook = Picqer\Api\PicqerWebhook::retrieveWithSecret('your-secret');
+```
+
+This will throw an `WebhookSignatureMismatchException` if the secret or signatures do not match.
 
 ## Support
 Need support implementing the Picqer API? Feel free to [contact us](https://picqer.com/contact)

examples/retrieveWebhook.php

@@ -0,0 +1,8 @@
+<?php
+
+require('../src/PicqerWebhook.php');
+
+$webhook = Picqer\Api\PicqerWebhook::retrieve();
+
+echo 'Hook received: ' . $webhook->getName() . ' that was triggered at ' . $webhook->getEventTriggeredAt() . PHP_EOL;
+echo $webhook->getData();

src/PicqerWebhook.php

@@ -0,0 +1,88 @@
+<?php
+
+namespace Picqer\Api;
+
+/**
+ * Picqer PHP Webhook helper
+ *
+ * @author Casper Bakker <info@picqer.com>
+ * @license http://creativecommons.org/licenses/MIT/ MIT
+ */
+class PicqerWebhook
+{
+    protected $idhook;
+    protected $name;
+    protected $event;
+    protected $data;
+    protected $event_triggered_at;
+
+    public function __construct($webhookPayload)
+    {
+        $this->rawPayload = $webhookPayload;
+
+        $fieldsToParse = ['idhook', 'name', 'event', 'data', 'event_triggered_at'];
+
+        foreach ($fieldsToParse as $field) {
+            if (array_key_exists($field, $webhookPayload)) {
+                $this->$field = $webhookPayload[$field];
+            }
+        }
+    }
+
+    public static function retrieve()
+    {
+        $webhookPayloadRaw = file_get_contents('php://input');
+
+        $webhookPayloadDecoded = json_decode($webhookPayloadRaw, true);
+
+        if ($webhookPayloadDecoded === false) {
+            throw new WebhookException('Could not decode webhook payload');
+        }
+
+        return new self($webhookPayloadDecoded);
+    }
+
+    public static function retrieveWithSecret($secret)
+    {
+        if (! isset($_SERVER) || ! array_key_exists('HTTP_X_PICQER_SIGNATURE', $_SERVER)) {
+            throw new WebhookSignatureMismatchException('Could not find signature header in webhook');
+        }
+
+        $webhookPayloadRaw = file_get_contents('php://input');
+
+        $signatureHeader = $_SERVER['HTTP_X_PICQER_SIGNATURE'];
+
+        $calculatedSignature = base64_encode(hash_hmac('sha256', $webhookPayloadRaw, $secret, true));
+
+        if (! hash_equals($calculatedSignature, $signatureHeader)) {
+            throw new WebhookSignatureMismatchException('Signatures do not match');
+        }
+
+        return self::retrieve();
+    }
+
+    public function getIdhook()
+    {
+        return $this->idhook;
+    }
+
+    public function getName()
+    {
+        return $this->name;
+    }
+
+    public function getEvent()
+    {
+        return $this->event;
+    }
+
+    public function getData()
+    {
+        return $this->data;
+    }
+
+    public function getEventTriggeredAt()
+    {
+        return $this->event_triggered_at;
+    }
+}

src/WebhookException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace Picqer\Api;
+
+class WebhookException extends Exception {}

src/WebhookSignatureMismatchException.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace Picqer\Api;
+
+class WebhookSignatureMismatchException extends Exception {}