---
title: "Extend Captcha Providers"
manual: "powermailcaptcha"
version: "3.4"
permalink: "https://docs.typo3.org/permalink/thomasrawiel/powermailcaptcha:extend@3.4"
source: "Configuration/ExtendCaptchaProviders.rst"
rendered: "2026-10-13T12:04:32+00:00"
---

# Extend Captcha Providers {#extend}

<!-- TODO: no Markdown rendering for "versionadded" -->

CAPTCHA validation can be extended and customized via two events:

## CaptchaConfigurationEvent {#captchaconfigurationevent}

The CAPTCHA provider configuration is extensible via the CaptchaConfigurationEvent. New providers can be added or existing ones overridden as long as they follow the expected configuration structure defined below.

Adjust or add providers: Use this event to modify the available CAPTCHA providers or their configuration before validation is executed.

Typical use cases:

-   Add a custom CAPTCHA provider
-   Override endpoints or request parameters
-   Change request methods (GET/POST)

**EXT:my_ext/Classes/EventListener/MyCaptchaConfigurationListener.php**

```php
final class MyCaptchaConfigurationListener
{
    public function __invoke(CaptchaConfigurationEvent $event): void
    {
        $configuration = $event->getConfiguration();

        $configuration['mycaptcha'] = [
            'siteVerifyUri' => 'https://example.com/verify',
            'verifyMethod' => 'POST',
            'responseKey' => 'my-captcha-response',
            'secretParameter' => 'secret',
            'responseParameter' => 'token',
        ];

        $event->setConfiguration($configuration);
    }
}
```

### CAPTCHA provider configuration {#captcha-provider-configuration}

Each CAPTCHA provider is defined via a configuration array that controls how the request is built and how the response is processed. These values allow the validation logic to remain provider-agnostic.

Available configuration keys

-   **siteVerifyUri**

    -   *Type:* string
    -   *Required:* true

    Example: [https://api.prosopo.io/siteverify](https://api.prosopo.io/siteverify)

    Defines the endpoint URL used for server-side verification of the CAPTCHA response.

    This URI is called during the verification request to the external CAPTCHA provider.

-   **verifyMethod**

    -   *Type:* string
    -   *Required:* true

    Allowed values: GET, POST

    Defines the HTTP method used when sending the verification request to the provider.

    GET: Parameters are appended to the query string
    POST: Parameters are sent as form_params in the request body

-   **responseKey**

    -   *Type:* string
    -   *Required:* true

    Example: procaptcha-response

    Defines the name of the field in the incoming frontend request that contains the CAPTCHA response token.

    This value is used to extract the CAPTCHA response from the submitted form data.

-   **secretParameter**

    -   *Type:* string
    -   *Required:* true

    Example: secret

    Defines the parameter name used to send the server-side secret key to the CAPTCHA provider.

    This key is included in the verification request payload.

-   **responseParameter**

    -   *Type:* string
    -   *Required:* true

    Example: token

    Defines the parameter name under which the CAPTCHA response token is sent to the provider during verification.

    This allows different providers to use different expected parameter names.

Examples can be found in the default provider configration shipped with the extension:

**EXT:powermailcaptcha/Classes/Domain/Validator/SpamShield/CaptchaMethod.php**

```php
$defaultCaptchaConfiguration = [
    'recaptcha' => [
        'siteVerifyUri' => 'https://www.google.com/recaptcha/api/siteverify',
        'verifyMethod' => 'GET',
        'responseKey' => 'g-recaptcha-response',
        'secretParameter' => 'secret',
        'responseParameter' => 'response',
    ],
    'friendlycaptcha' => [
        'siteVerifyUri' => 'https://api.friendlycaptcha.com/api/v1/siteverify',
        'verifyMethod' => 'POST',
        'responseKey' => 'frc-captcha-solution',
        'secretParameter' => 'secret',
        'responseParameter' => 'solution',
    ],
    'hcaptcha' => [
        'siteVerifyUri' => 'https://hcaptcha.com/siteverify',
        'verifyMethod' => 'POST',
        'responseKey' => 'h-captcha-response',
        'secretParameter' => 'secret',
        'responseParameter' => 'response',
    ],
    'cloudflare' => [
        'siteVerifyUri' => 'https://challenges.cloudflare.com/turnstile/v0/siteverify',
        'verifyMethod' => 'POST',
        'responseKey' => 'cf-turnstile-response',
        'secretParameter' => 'secret',
        'responseParameter' => 'response',
    ],
    'procaptcha' => [
        'siteVerifyUri' => 'https://api.prosopo.io/siteverify',
        'verifyMethod' => 'POST',
        'responseKey' => 'procaptcha-response',
        'secretParameter' => 'secret',
        'responseParameter' => 'token',
    ],
];
```

## ExpectedResponseEvent {#expectedresponseevent}

Define validation logic: Use this event to control how the raw provider response is interpreted and converted into a boolean validation result.

Typical use cases:

-   Implement provider-specific validation logic
-   Override default success criteria
-   Handle non-standard API responses

Example:

**EXT:my_ext/Classes/EventListener/MyExpectedResponseListener.php**

```php
final class MyExpectedResponseListener
{
    public function __invoke(ExpectedResponseEvent $event): void
    {
        $configuration = $event->getConfiguration();
        $result = $event->getResult();

        if (($configuration['captchaMethod'] ?? null) === 'mycaptcha') {
            $event->setResponse(
                ($result->status ?? null) === 'valid'
                && ($result->score ?? 0) > 0.5
            );
        }
    }
}
```

### How both events work together {#how-both-events-work-together}

`CaptchaConfigurationEvent` defines how a provider is called

`ExpectedResponseEvent` defines how the response is interpreted

This separation allows you to fully integrate custom CAPTCHA providers without modifying core logic.