Webhook Signing

When you register for webhooks we will assign a "secret". This should be kept securely (do not commit to source control).

We will create a signature using this secret and a timestamp. You should use the secret to validate this signature.

We add the following headers, which you will need to extract:

    'Content-Type' => 'application/json',
    'X-Webhook-Signature' => $signature,
    'X-Webhook-Timestamp' => (string)$timestamp,
    'X-Webhook-ID' => $webhookId,
    'User-Agent' => 'NRSDB-Webhooks/1.0',

The "payload" is added to the body of the message

$body = (string)$request->getBody();
$payload = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

You can use the $webhookId to make sure you don't process the same event twice.

Sample PHP code to validate the message using the $signature and $secret is shown below;

    /**
     * Verify signature with timestamp (for recipients)
     */
    public static function verifyWebhookWithTimestamp(
        string $payload,
        string $signature,
        string $secret,
        int $timestamp
    ): bool {
        $signedData = $payload . $timestamp;
        $expectedSignature = hash_hmac('sha256', $signedData, $secret);

        return hash_equals($expectedSignature, $signature);
    }