Webhook (under maintenance)

Explanation and illustration of our webhook service, which triggers your callbackUrl(upon task creation) to provide results.

1. A valid URL meets the following conditions:

• Start with https://

• Response time is less than 10 seconds

• The host is not set to localhost

2. Webhook Body (with POST method)

// Similar to the result when calling get task result api

{
  "id": "6547c1d4933dfb372b6f94f5",
  "result": {
    "token": "03AFcWeA6Zlknk3NHIMZnLeebiV-XRkZXUcJSH2zstNa5syiHCZhhznXgTwXsTcVgdJiRW-eP_CxwnFOwY8l_VLw7t-z5V1I3U-NVtufcLbM7-ocenzDN2zimerh-CUAb0hzotrPCBc655kETRe3TZGXjB9kzogM7hYpRd26-C-GjpitYScVXCENzuybObR3H3yRAchKlszBYx8ZU95U5aXrrt9bOTgvT4ePTQqBOV1SPTbFZcUBjTfHQFUFV1sij30aLgS8F0c9oWJA_d-ofweMAwRlY6wIYzGabczf9ktKpEpSfygCwSrYgYOG5Irt7vn_6z1RLiNdnsSdxnWvD5_Nb1haN6ozolTxYvXj0aXnK_NHBXFuClyzp9SV2n8zsXnMdR0FQE2Ra0M4-jAK_Xd_ncYXfFHOV4gFeMPi0YNVIidX07Wex0snupFFDOyUCAfKmjcrUGqa5UcgLFN3VRpCrNclJPWlfu8Q5TY_xeJaI90NQdAiR6gPLUSq8hc7-M4kouJFv_RWkZewKoPHHa5ssJruu8leqvNMyf6dwprP2kKKC_30pSuDgCAzIfoSs-e1lmyk4423dd"
  },
  "status": "SUCCESS"
}

// or

  "id": "6547c36e933dfb372b6f94f6",
  "result": {
    "token": null
  },
  "status": "FAILED"
}

3. Verify the webhook

Before you respond to a webhook, you need to verify that the webhook was sent from HardCaptcha. You can verify the webhook by calculating a digital signature.

Each webhook request includes a X-HardCaptcha-Hmac-SHA256 header, which is generated using your API key along with the data sent in the request.

• Compute the HMAC digest according to the following sha256 algorithm

• Compare the computed value to the value in the X-HardCaptcha-Hmac-SHA256 header

NodeJS

const hmac = createHmac('sha256', 'YOUR_API_KEY')
  .update(rawBody)
  .digest('hex');

const isValid = req.headers['hmac'] === hmac;

PHP

<?php

// Assuming you have rawBody and YOUR_API_KEY available
$rawBody = "your_raw_body_here";
$apiKey = "YOUR_API_KEY";

$hmac = hash_hmac('sha256', $rawBody, $apiKey);

// Assuming you have req object available
$isValid = isset($_SERVER['HTTP_HMAC']) && $_SERVER['HTTP_HMAC'] === $hmac;

?>

Python

import hashlib
import hmac

api_key = 'YOUR_API_KEY'
raw_body = 'your_raw_body_content'  # Replace with the actual raw body content
provided_hmac = 'provided_hmac_from_request'  # Replace with the actual HMAC from the request headers

computed_hmac = hmac.new(api_key.encode('utf-8'), raw_body.encode('utf-8'), hashlib.sha256).hexdigest()

is_valid = provided_hmac == computed_hmac

print(is_valid)

Golang

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
)

func main() {
	apiKey := "YOUR_API_KEY"
	rawBody := "your_raw_body_content"

	hash := hmac.New(sha256.New, []byte(apiKey))
	hash.Write([]byte(rawBody))
	hmacValue := hex.EncodeToString(hash.Sum(nil))

	// Assuming reqHeader is a variable representing the request headers in Golang
	reqHeader := make(map[string]string)
	reqHeader["hmac"] = "your_received_hmac_header"

	isValid := reqHeader["hmac"] == hmacValue

	fmt.Printf("Is Request Valid: %t\n", isValid)
}

C#

using System;
using System.Security.Cryptography;
using System.Text;

class Program
{
    static void Main()
    {
        string apiKey = "YOUR_API_KEY";
        string rawBody = "your_raw_body_content";

        using (HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiKey)))
        {
            byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawBody));
            string hmacValue = BitConverter.ToString(hashBytes).Replace("-", "").ToLower();

            // Assuming headers is a variable representing the request headers in C#
            var headers = new System.Collections.Generic.Dictionary<string, string>();
            headers["hmac"] = "your_received_hmac_header";

            bool isValid = headers["hmac"].Equals(hmacValue, StringComparison.OrdinalIgnoreCase);

            Console.WriteLine($"Is Request Valid: {isValid}");
        }
    }
}

4. Response

Your webhook acknowledges that it received data by sending a 20x OK response. Any response outside of the 20x range, including 3XX HTTP redirection codes, indicates that you didn't receive the webhook.

Request timeout: 5 seconds

Retry frequency: 3 three times with a backoff period of 5 seconds.