Truform Captcha

Webhooks

Quota, verification, risk, and threat notifications for Truform subscriptions.

Truform sends HTTPS POST notifications for quota usage, verification outcomes, elevated risk, and suspicious traffic. Configure webhooks on the Truform service page in the Syndaq client area.

Events

EventWhen it fires
quota.thresholdService usage reaches 80% of the monthly quota (once per month)
quota.exceededService usage reaches or exceeds the monthly quota (once per month)
verification.succeededA browser verify completes and returns a proof token
verification.failedA browser verify fails or requires an enhanced puzzle
risk.elevatedRisk scoring triggers an enhanced (hard) challenge requirement
threat.suspiciousAutomated threat detection (Enterprise), such as token farming

Starter plans receive quota events only. Developer and Enterprise plans can toggle all events in the client area.

Payload

Each delivery is a JSON POST:

{
  "event": "verification.succeeded",
  "timestamp": "2026-05-19T14:30:00+00:00",
  "client_service_id": 2,
  "data": {
    "public_key": "tf_pub_...",
    "risk_score": 22,
    "risk_level": "low",
    "difficulty": "normal",
    "action": "login"
  }
}

Quota events include monthly_quota, month_usage, quota_pct, and quota_period in data.

Signature

When a webhook is saved, Syndaq generates a signing secret. Verify deliveries with the X-Syndaq-Signature header:

X-Syndaq-Signature: sha256=<hex_hmac_sha256_of_raw_body>

Reveal the signing secret from the Truform service page (Developer+). Compare using a constant-time function.

Delivery and retries

Syndaq records each delivery attempt. Failed deliveries (non-2xx or timeout) retry with exponential backoff up to five attempts. View the delivery log on the service page and replay individual events on Developer and Enterprise plans.

Run the platform cron worker periodically:

php private/cron/truform_webhook_retry.php

Endpoint requirements

  • Must be HTTPS
  • Should respond with HTTP 2xx within a few seconds
  • Should be idempotent (retries may deliver the same event again)