Request Verification

Request verification allows you to confirm that it's Omneo sending your plugin a HTTP request. Without this, your plugin is vulnerable to attack

Verification process

If your plugin is going to receive webhook or trigger requests from Omneo, you will need a mechanism of verifying the request to ensure it's actually from Omneo. Without request verification, your app could be vulnerable to request spoofing.

Requests sent by Omneo include a X-Omneo-Hmac-SHA256 header containing a HMAC signature. This signature is securely generated from the payload of request and signed using a shared key.

To verify that's it is Omneo sending the request, all you need to do is generate the signature in the same way and sign it using the same shared key. If your signature and the signature in X-Omneo-Hmac-SHA256 match, we're safe to proceed 🔒

HMAC signature verification can be a little tricky to get right so we have included a verification method in the client.

To use any of the built-in verification methods below, ensure that you have set your shared secret on your client instance.

$omneo->setSecret('foobar');

Plain PHP

To use the built-in verification logic, your server request will need to implement Psr\Http\Message\ServerRequestInterface or in other words, be compliant with PSR-7. Consult documentation for your framework on how to get a PSR-7 compatible instance of your server request.

By passing your request to the verify() method, a signature will be generated from the payload and compared against the Omneo header.

If verification fails, a RequestVerificationException will be thrown. You should halt execution and no longer trust that the request came from Omneo.

If verification passes, the method will return void and you can continue with the execution of your plugin.

// @throws Omneo\Exceptions\RequestVerificationException
$omneo->requestVerifier()->verify(
    $request // PSR-7 compatible request
);

Laravel

With middleware

We have included a handy middleware for protecting your Omneo routes. To enable it, add the following to your HTTP kernel $routeMiddleware property.

app/Http/Kernel.php

protected $routeMiddleware = [
    'verify.omneo' => \Omneo\Laravel\VerifyRequestMiddleware::class
]

Now that your middleware is registered, you may protect your routes.

Route::middleware('verify.omneo')
    ->post('omneo', 'OmneoWebhookController@receive');

Without middleware

If you cannot use the middleware for some reason, you may directly validate the request against the client.

FooController.php

public function receive(Request $request, Omneo\Client $omneo)
{
    // We need to convert Illuminate\Http\Request to a PSR-7 request
    $psrRequest = (new DiactorosFactory)->createRequest($request);
    
    // If no exception is thrown, we are safe to continue
    $omneo->requestVerifier()->verify($psrRequest);
    
    // Do dangerous things
    // ...
}