API and Webhooks

The Integrations settings tab configures TrustLens’s REST API access and outgoing webhook delivery. The REST API exposes customer scores, events, 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 → Integrations → REST API (and Integrations → Webhooks).

---

REST API Access #

Availability #

The REST API is always available, in Free and Pro; there is no on/off switch. Every endpoint requires authentication, so nothing is exposed until you give a client credentials.

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 the key with Generate API Key on the REST API section, and replace it with Regenerate (the old key stops working). Copy the key when it’s generated — afterwards the page only confirms that a key is set. The section also shows the base URL for all requests.

---

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 (query: segment, blocked, per_page, page, orderby, order)
/customers/lookup	GET	Look up a customer by raw email
/customers/{hash}	GET	Get full customer record
/customers/{hash}	POST/PUT/PATCH	Update block and allowlist state (is_blocked, is_allowlisted)
/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. Admin notes and tags can’t be changed through the API.

See REST API Reference for full request/response schemas.

---

Outgoing Webhook Settings (Pro) #

Enable Webhooks #

Default: Off

Master switch for the webhooks configured on this tab. Automation rules with a Send Webhook action are separate and don’t depend on it.

Webhook Endpoints #

Add as many endpoints as you need with Add Webhook Endpoint. Each has:

• Endpoint URL — events are delivered here as a JSON POST request
• Signing secret (optional) — if set, every payload is signed with HMAC-SHA256 in the X-TrustLens-Signature header; leave blank to skip signing
• Endpoint is active — on/off per endpoint

The endpoints table shows each URL (with a lock icon when it’s signed), its events, and Test and Delete buttons.

Delivery #

Settings webhooks are sent once, without waiting for the response (non-blocking, 15-second timeout) and without retries. Each request carries X-TrustLens-Event, X-TrustLens-Delivery, X-TrustLens-Webhook-ID, and X-TrustLens-Timestamp headers; the signature covers the timestamp and the body.

Automation Send Webhook actions work differently: they are always signed (with an auto-generated per-install secret), wait up to 10 seconds for a 2xx response, and retry 3 times with 60/120/240 second backoff. See Async Dispatch & Retries for the full retry model.

---

Webhook Event Subscription (Pro) #

Under Events to Send, choose which events the Settings webhooks deliver. The subscribable events are:

• score_updated — a customer’s trust score was recalculated
• 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

The defaults are score_updated, customer_blocked, checkout_blocked, and high_risk_order. The selection applies to all endpoints.

---

Custom Headers #

There is no setting for custom HTTP headers. If a receiver needs its own authentication token, put it in the endpoint URL (for example as a query parameter your receiver checks) or verify the HMAC signature instead.

---

Testing #

Test Webhook #

The Test button on an endpoint sends a synthetic test event to that endpoint (signed if it has a secret) and reports whether it answered successfully. Useful for verifying the receiver is reachable, the secret is correct, and the payload format is what you expect.

Testing the API #

The REST API section shows the available endpoints, an example request, and an example response. There is no in-page request tool; use curl or an API client with your key to verify authentication before pointing a real integration at it.

---

API Logs #

TrustLens doesn’t log REST API requests. Use your web server’s access log if you need a record of API traffic.

---

Webhook Logs #

The Recent Webhook Deliveries table lists recent Settings webhook sends — event, endpoint, and time — and keeps the most recent 1,000. Because delivery doesn’t wait for a response, the log records that a delivery was sent, not whether the receiver accepted it. Automation webhook results appear in the automation log. See Webhooks and HMAC for the receiver-side implementation.

---

Security Considerations #

• API access is admin-level. The API key grants full access to every TrustLens endpoint, and there are no scoped keys. Don’t expose it to untrusted parties; regenerate it if it leaks.
• Use HTTPS webhook URLs. Webhook bodies contain customer data — email addresses, scores, and order details — and the signing secret is only as safe as the channel.
• Signing secrets are stored in the database as entered. Treat database access and backups accordingly; only the API key is stored hashed.
• Rate limits belong at your infrastructure layer. TrustLens doesn’t rate-limit API requests.

---

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_updated webhooks; insert into warehouse table
• Help desk integration: Helpdesk app calls /customers/lookup with the customer’s email when an agent opens a ticket
• Custom fraud rule engine: External service consumes TrustLens webhooks, applies its own logic, then PATCHes /customers/{hash} with is_blocked: true if needed