Send hCaptcha task feedback after observing the outcome

Report accepted and rejected results through the SDK feedback methods, and separate actual failures from local timeouts or unknown outcomes.

Observe what the result did

Feedback should describe the result’s observed outcome. A token arriving or a recognition job completing only establishes that the solver returned something. It does not establish whether your integration accepted it or completed the intended action.

Record the task ID at creation and carry it through the application flow. That gives the final observer a way to report the right job instead of attaching an outcome to whichever task happened to finish most recently.

Call the public feedback method

import os
from easycaptcha.backends.urllib import UrllibClient

def report_observed_outcome(task_id: str, accepted: bool) -> None:
    with UrllibClient(os.environ["EASYCAPTCHA_API_KEY"]) as client:
        client.send_feedback(task_id, success=accepted)

The JavaScript equivalent is await client.sendFeedback(taskId, accepted). accepted must come from your integration’s observation, not from a check that the API body contains a result field.

Keep the account credential separate from task data. A task ID identifies the work but does not grant access to it. Use the customer key for the account that owns the task.

Leave unknown outcomes unknown

If the browser closes before submission, you may not know whether a token would have been accepted. If an application request times out, you may not know whether the protected operation completed. Do not convert either into negative feedback solely to make a report contain no missing values.

Likewise, a valid proof followed by a rejected form field is a different application outcome from proof rejection. Decide which event your feedback source observes and document that decision. Your analytics can keep additional stages even when the feedback method takes only a boolean.

Keep reporting auditable

Store the observation stage and timestamp with the task ID in your own records. Keep tokens, passwords, and private form content out of general logs. If feedback delivery itself fails, retain that delivery state rather than resubmitting the original solving job.

Consult the API reference for feedback rules and errors. The measurement guide explains outcome denominators, while unknown-outcome reporting helps keep missing observations visible instead of presenting them as verified failures.