Security

Listening to a webhook implies exposing an URL (the webhook endpoint) to the web. As the endpoint needs to be public and anyone can call it, it is insecure by default.

The solution implies MeetingLawyers to hash each request payload with a secret, creating a signature. This resulting signature will be included in the headers of the request, which you can then use to verify that the contents are not tainted or altered.

This page shows you how to configure secrets in webhooks so that they get signed, and how to verify those signatures in your app to maintain the data integrity of your application. It can be done by verifying the signature of the payload which will be sent in the request header X-Signature.

info

We do not currently have designated IPs for webhook requests. We use dynamic IP addresses, so we cannot guarantee a static IP address or even a range of IP addresses.

Protocol

We strongly encourage using HTTPS for your webhook endpoint. HTTP is also supported but firmly discouraged.

When using HTTPS, your SSL/TLS certificate must be validated — self-signed certificates will not work.

Set up your webhook secret

1. Generate a random string, something between 16 and 32 characters should be good.

OpenSSL

openssl rand -hex 20

Hexdump

xxd -u -l 20 -p /dev/urandom

Ruby

ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'

2. Request our technical team to update your company webhook secret.

Validate request

To validate the received webhook, you will have to generate a signature from the payload using your secret; then,you will need to compare it with the received one.

1. Using the HMAC SHA-256 algorithm, create a hash of the entire body as binary, using your webhook secret as a key).
2. Encode the binary hash in base64 format.
3. Add prefix sha256= to the base64 hash.
4. Compare the created value with the signature you received in the X-Signature header.

Here are some examples:

PHP/Symfony

WebhookController.php

use Symfony\Component\HttpKernel\Exception\HttpException;

use Symfony\Component\HttpFoundation\Request;

use Symfony\Component\HttpFoundation\Response;

use Symfony\Component\Routing\Annotation\Route;

class WebhookController {

const WEBHOOK_SECRET = '...'

#[Route('/webhook', name: 'webhook')]

public function webhookAction(Request $request): Response {

$this->verifySignature($request->headers()->get('X-Signature'), $request->getBody());

return new Response(200, 'Payload received: ' . $request->getBody());

}

private function verifySignature(string $signatureReceived, string $payloadBody): bool {

$actualSignature = 'sha256=' . base64_encode(hash_hmac('sha256', $payloadBody, self::SECRET, true));

if ($actualSignature !== $signatureReceived) {

throw new HttpException(401, 'Not matching signatures!');

}

}

}

Ruby

webhook.rb

request.body.rewind

payload_body = request.body.read

verify_signature(request.env['HTTP_X_SIGNATURE'], payload_body)

"Payload received: #{payload_body.inspect}"

end

def verify_signature(received_signature, payload_body)

hash = OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), ENV['WEBHOOK_SECRET'], payload_body)

actual_signature = 'sha256=' + Base64.strict_encode64(hash)

return halt 401, "Not matching signatures!" unless Rack::Utils.secure_compare(actual_signature, received_signature)

end

caution

Take into consideration that line-breaks and other non-visible characters on the request could make the debugging of your signature code a hard task when trying to fake the request body by just copy-pasting it.