View Categories

API and Webhooks

3 min read

The API and Webhooks settings tab configures TrustLens’s REST API access and outgoing webhook delivery. The REST API exposes customer scores, signals, and segment data for integration with external systems. Outgoing webhooks let TrustLens push events to your CRM, helpdesk, or custom internal tools. This page covers settings on the tab; for the full API surface, see the developer documentation.

Location: TrustLens → Settings → API (and Settings → Webhooks).

REST API Access #

REST API Enabled #

Default: On

Master toggle for the TrustLens REST API. When off, all /wp-json/trustlens/v1/* endpoints return 404.

Authentication Methods #

TrustLens accepts two authentication mechanisms:

  1. WordPress user authentication. Any authenticated user with the manage_woocommerce capability. Commonly implemented via WordPress application passwords in HTTP Basic Auth.
  2. TrustLens API Key. A static key sent in the X-TrustLens-API-Key header. The key is stored as a SHA-256 hash in the trustlens_api_key option and compared with timing-safe hash_equals().

Generate or rotate the API key in Settings → API → API Key. The key is shown once at generation and masked thereafter.

Rate Limiting #

The plugin does not enforce application-level rate limits on REST API requests. If you need rate limiting for your deployment, apply it at the web server (nginx, Apache), reverse proxy (Cloudflare, CDN), or WAF layer.

This is a deliberate design choice — rate limiting at the application layer is duplicative with infrastructure-level controls that most production WordPress deployments already have, and it adds latency to every request.

Endpoints Available #

The 8 REST endpoints (all under /wp-json/trustlens/v1/):

Endpoint Method Description
/customers GET List customers with filtering and pagination
/customers/lookup GET Look up a customer by raw email
/customers/{hash} GET Get full customer record
/customers/{hash} POST/PUT/PATCH Update mutable state (is_blocked, is_allowlisted, admin_notes, tags)
/customers/{hash}/events GET List events from the customer timeline
/customers/{hash}/recalculate POST Trigger immediate score recalculation
/stats GET Store-wide aggregate statistics
/stats/segments GET Segment distribution counts

All endpoints require authentication. There are no separate /block, /allowlist, or /disputes endpoints — block and allowlist state are set via PATCH on the customer record, and dispute data is exposed via the customer record’s stat columns and events.

See REST API Reference for full request/response schemas.

Outgoing Webhook Settings #

Global Webhook URL (Pro) #

If set, all TrustLens events fire to this URL in addition to any per-automation-rule webhooks. Useful for sending a firehose of events to a central event-collection system.

Global Webhook Secret (Pro) #

HMAC-SHA256 signing key for the global webhook. Auto-generated.

Webhook Timeout #

Default: 10 seconds

How long to wait for webhook receivers to respond before considering the delivery failed.

Webhook Retry Policy #

Default: 3 retries with 60/120/240 second backoff

See Async Dispatch & Retries for the full retry model.

Webhook Event Subscription (Pro) #

For the global webhook, you can subscribe to specific event types rather than receiving all events. The subscribable events are:

  • score_updated — a customer’s trust score changed
  • customer_blocked — a customer was blocked
  • customer_unblocked — a block was removed
  • customer_allowlisted — a customer was allowlisted
  • customer_allowlist_removed — an allowlist entry was removed
  • checkout_blocked — a checkout was blocked by enforcement
  • high_risk_order — an order was placed by a high-risk customer
  • automation_triggered — a Pro automation rule fired

Custom Headers (Pro) #

Add custom HTTP headers to all outgoing webhooks. Useful for:

  • Routing to specific destinations on a multi-tenant receiver
  • Authentication tokens for receivers that require them in addition to HMAC
  • Versioning headers

Headers are sent on every webhook from this TrustLens instance.

Testing #

Send Test Webhook #

Button to fire a synthetic test event to the configured global webhook URL. Useful for verifying the receiver is reachable, the secret is correct, and the payload format is what you expect.

Test API Endpoint #

Inline tool that lets you make a sample API request directly from the settings page and see the response. Useful for verifying authentication is working before pointing a real integration at it.

API Logs #

The Activity Log tab shows recent API requests:

  • Timestamp
  • Authenticated user
  • Endpoint
  • Response status
  • Response time

Useful for confirming API integrations are running correctly, spotting unexpected request patterns, and debugging authentication issues.

Webhook Logs #

Similarly, the Webhook Activity Log shows recent outgoing webhook deliveries with attempt status, retry counts, and receiver responses. See Webhooks and HMAC for the receiver-side implementation.

Security Considerations #

  • API access is admin-level. Don’t expose API credentials to untrusted parties. Use scoped API keys (Pro) for partner integrations.
  • Webhook URLs should be HTTPS. TrustLens warns when configuring HTTP-only webhook URLs.
  • HMAC secrets are stored encrypted at rest. They’re shown only at creation time; thereafter masked.
  • Rate limits protect against abuse. Lower them if you’re seeing suspicious traffic.

Common Integration Patterns #

  • Read customer score from CRM: CRM pulls /customers/{hash} when displaying a customer record
  • Sync customer state to data warehouse: Subscribe to score_changed webhooks; insert into warehouse table
  • Help desk integration: Helpdesk app calls /customers/{hash} when an agent opens a ticket from a customer
  • Custom fraud rule engine: External service consumes TrustLens webhooks, applies its own logic, then PATCHes /customers/{hash} with is_blocked: true if needed
Updated on June 18, 2026

What are your Feelings

  • Happy
  • Normal
  • Sad