How to Use TrustLens Webhooks to Sync WooCommerce Customer Risk With Your CRM or Helpdesk

Most store owners who use TrustLens start by looking at the dashboard. They see the segment distribution, read a customer profile, and decide what to do. That works fine for a solo operator who logs in every morning and reviews the night’s activity.

It breaks down in two common situations. The first is speed: a Critical-segment customer placing a $400 order at 2 a.m. on a Friday is not going to wait for you to open the dashboard Monday morning. The second is context: your support team fielding a refund dispute does not want to leave Zendesk, switch to WordPress, find the customer, and check the trust score manually. They want the score to already be there when the ticket opens.

TrustLens Pro addresses both with two integration surfaces: webhooks that push trust events to external systems in real time, and a REST API (available in the free version) that lets any authorized tool pull customer data on demand. This guide covers both — what each delivers, how to implement them, and where the free/Pro line falls.

Why Push Risk Data Out of WooCommerce at All

TrustLens assigns every WooCommerce customer a trust score from 0 to 100 and places them in one of six segments: VIP, Trusted, Normal, Caution, Risk, or Critical. Eight detection modules feed that score — returns, order patterns, coupon behavior, linked accounts, shipping anomalies, chargebacks, and card-testing attacks. By the time a customer’s score moves, there is a meaningful behavioral reason for it.

That data is most valuable when the people who need it can access it without switching context. Consider three scenarios:

• A support agent opens a refund ticket in Zendesk. The customer filed two chargebacks last quarter. If the trust score is visible on the ticket, the agent handles the conversation differently than if they have to go look it up — or worse, never look it up at all.
• A HubSpot contact record flags a customer’s marketing segment as high-value. TrustLens knows the same customer is in the Risk segment. If the two systems do not talk, marketing keeps sending VIP-level promotions to someone who is actively abusing the store.
• A customer reaches Critical segment at 11 p.m. Slack can receive a webhook and post a notification to your fraud channel within seconds. Your on-call person can review the account before the next order lands.

Webhooks make this possible by pushing data outward the moment something changes. The REST API makes it possible by letting other systems pull data whenever they need a current snapshot. Together, they turn TrustLens from a WooCommerce admin tool into a shared data source that any part of your operations stack can consume.

Webhooks vs. REST API: Which Tool for Which Job

These two integration surfaces solve different problems, and understanding the distinction before you build anything saves a lot of architectural rework.

Webhooks (Pro) are event-driven: TrustLens fires an HTTP POST to your endpoint the moment a specific event happens. Your receiver does not have to ask — it just has to be listening. Use webhooks when you want to react to changes as they occur: flagging a CRM contact when a customer’s segment changes, opening a ticket when a checkout is blocked, posting to Slack when a high-risk order lands.

The REST API (free) is request-driven: your external system calls TrustLens when it needs data. The API does not know what you are doing with the response. Use the REST API when you need a current snapshot at a specific moment — loading a trust score when a support ticket opens, pulling a segment list to sync with your email platform nightly, or triggering a score recalculation after you have manually reviewed an account.

For most CRM and helpdesk integrations, you will use both: webhooks to push changes in real time, and the REST API to populate an initial sync or to fetch the current state when a ticket opens on a customer you have not received a recent event for.

The Webhook Event Types

TrustLens Pro webhooks fire on seven event types. You can enable or disable each event type per endpoint, so a Slack alerting endpoint can receive only high_risk_order events while a CRM endpoint receives score_updated and customer_blocked separately.

These event types are verified against the class-webhooks.php source in TrustLens version 1.2.5:

What a Webhook Payload Looks Like

Every TrustLens webhook delivery is a JSON body sent via HTTP POST. The top-level structure is consistent across all event types: an event field identifying the type, a timestamp in ISO 8601 format, a customer object with the full behavioral snapshot, event-specific fields, and a site object identifying the originating store.

A score_updated payload looks like this (fields verified against source code):

{
  "event": "score_updated",
  "timestamp": "2026-06-05T14:23:00+00:00",
  "customer": {
    "email_hash": "a3f2...64 hex chars",
    "email": "[email protected]",
    "trust_score": 34,
    "segment": "risk",
    "total_orders": 12,
    "total_refunds": 5,
    "return_rate": 41.7,
    "is_blocked": false,
    "is_allowlisted": false
  },
  "new_score": 34,
  "new_segment": "risk",
  "site": {
    "url": "https://yourstore.com",
    "name": "Your Store"
  }
}

A high_risk_order payload adds the order object:

{
  "event": "high_risk_order",
  "timestamp": "2026-06-05T14:31:00+00:00",
  "customer": { ... },
  "order": {
    "id": 4821,
    "number": "4821",
    "total": 249.00,
    "currency": "USD",
    "status": "processing"
  },
  "site": { ... }
}

Two things worth noting about the customer object. First, the email field contains the customer’s email address as stored by TrustLens — but TrustLens identifies customers by an HMAC-SHA256 hash of the email, not the raw address. Both are present in the payload, so your receiver can use whichever is more appropriate for your integration. Second, total_refunds is a count of refund transactions, while return_rate is the percentage of orders that ended in a refund. Both are useful but measure different things.

Verifying the Signature (HMAC-SHA256 v2 Scheme)

TrustLens signs every webhook delivery using HMAC-SHA256. Understanding what is being signed and how to verify it matters because an unverified webhook receiver can be spoofed — anyone who knows your endpoint URL could send a fake payload if you do not check the signature.

As of TrustLens version 1.2.3, the signature scheme is v2: the signature covers both the timestamp and the request body together, not just the body alone. This is a meaningful security improvement. A body-only signature can be replayed indefinitely if an attacker captures a delivery. A timestamp-plus-body signature becomes stale as soon as the timestamp falls outside your acceptable window.

What TrustLens sends

Every delivery includes three custom HTTP headers in addition to the standard Content-Type: application/json:

• X-TrustLens-Event — the event type string (e.g. score_updated)
• X-TrustLens-Timestamp — the Unix epoch at delivery time (e.g. 1749131460)
• X-TrustLens-Signature — the HMAC-SHA256 hex digest, prefixed with sha256=

Additionally, X-TrustLens-Delivery (a UUID per delivery) and X-TrustLens-Webhook-ID (the endpoint’s UUID from your settings) are included for logging and idempotency purposes.

How the signature is computed

The signed string is the timestamp, a literal period, and the raw JSON body:

signed_string = timestamp + "." + body
signature = "sha256=" + HMAC_SHA256(signed_string, your_secret)

This is verified against TrustLens source code in TrustLens_Webhooks::compute_signature() (version 1.2.3+). The timestamp in the signed string is the integer value of the X-TrustLens-Timestamp header, and body is the raw request body bytes — before any JSON parsing.

Receiver verification in Python

import hmac, hashlib, time

def verify_trustlens_webhook(body_bytes, signature_header, timestamp_header, secret, max_age_seconds=300):
    # 1. Reject obviously old deliveries before doing any crypto
    ts = int(timestamp_header)
    if abs(time.time() - ts) > max_age_seconds:
        return False  # too old or too far in the future

    # 2. Compute expected signature
    signed_string = f"{ts}.{body_bytes.decode('utf-8')}"
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"),
        signed_string.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()

    # 3. Constant-time compare to prevent timing attacks
    return hmac.compare_digest(expected, signature_header)

Receiver verification in Node.js

const crypto = require("crypto");

function verifyTrustLensWebhook(rawBody, signatureHeader, timestampHeader, secret, maxAgeSeconds = 300) {
  // 1. Reject obviously old deliveries
  const ts = parseInt(timestampHeader, 10);
  if (Math.abs(Date.now() / 1000 - ts) > maxAgeSeconds) {
    return false;
  }

  // 2. Compute expected signature
  const signedString = `${ts}.${rawBody}`;
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(signedString)
    .digest("hex");

  // 3. Constant-time compare
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

A few implementation notes worth keeping in mind:

• Compute the signature against the raw request body bytes, not a re-serialized JSON object. JSON libraries may reorder keys or normalize whitespace in ways that change the bytes.
• Use a constant-time comparison function (hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js). Standard string equality is vulnerable to timing attacks that can leak the secret byte by byte.
• The recommended replay window is 5 minutes (300 seconds) in both directions — that is, reject deliveries where the timestamp differs from the current time by more than 5 minutes. A smaller window is safer; a window larger than 15 minutes is not advisable.
• If your endpoint is behind a load balancer or API gateway that rewrites the body, verify the signature before the gateway transforms the payload.

Setting Up a Webhook Endpoint in TrustLens

Webhook endpoints are managed at TrustLens → Settings → Webhooks in the WordPress admin (Pro license required). The setup for a new endpoint is three fields:

TrustLens supports multiple endpoints simultaneously. You might have one sending high_risk_order and customer_blocked to a Slack webhook URL and a second sending score_updated to your CRM. Each endpoint has its own event subscriptions, secret, and delivery log.

One important note on delivery mode: production webhooks fire non-blocking (the WordPress HTTP request does not wait for a response before the site continues). This is good for performance but means your endpoint’s response code is only logged, not used to determine whether the delivery succeeded in a way that would re-queue it. The non-blocking architecture is why the delivery log exists — it captures what was sent and to which endpoint so you can audit it even if you cannot always see the response synchronously.

Integration Patterns: HubSpot, Zendesk, Slack, and Custom Receivers

The patterns below are illustrative examples of how each destination typically consumes TrustLens webhook data. They are not step-by-step configuration guides for specific third-party platforms — those details change as those platforms update their APIs — but they describe the data flow and the design decisions worth making in advance.

HubSpot: flagging Risk and Critical customers in your CRM

HubSpot supports incoming webhooks through its Operations Hub workflows (paid tiers) and through custom code actions. The typical integration pattern is:

1. Subscribe your HubSpot workflow webhook receiver URL to score_updated and customer_blocked in TrustLens.
2. In the receiver, extract the customer.email field from the payload and look up the contact in HubSpot by email address.
3. Update a custom contact property (e.g. “TrustLens Segment” or “Trust Score”) with the values from the payload’s new_segment and new_score fields.
4. Optionally, use HubSpot’s workflow enrollment criteria to trigger other actions — suppress marketing emails for Risk or Critical contacts, route them to a deal-review stage, or notify a sales rep.

The score_updated event fires every time a score changes, so it is noisy for high-volume stores. If you only want CRM updates at segment transitions, consider filtering in your receiver: ignore events where new_segment matches the value you have already stored on the contact. Alternatively, use an Automation Rule with the Segment Changed trigger and the Send Webhook action (Pro) — that way TrustLens only fires the delivery when the segment actually changes, and you do not have to filter in the receiver.

Zendesk: surfacing trust data on support tickets

There are two ways to get TrustLens data into Zendesk. The webhook approach uses Zendesk’s Triggers and HTTP targets (available on Suite plans) to receive incoming data. The REST API approach uses a Zendesk app or sidebar widget that queries TrustLens on demand when an agent opens a ticket.

For the webhook approach: TrustLens fires customer_blocked or high_risk_order to a Zendesk HTTP target, which can be configured to open a ticket, add a tag, or update a user field. The customer’s email from the payload is the link point — Zendesk can match it to an existing user record.

For the REST API approach: a Zendesk sidebar app calls the TrustLens REST API endpoint GET /wp-json/trustlens/v1/customers/lookup?email={requester_email} when the agent opens a ticket. The response includes the customer’s current trust score, segment, total orders, return rate, and block status — all readable without a Pro license. This gives support agents live context without requiring any webhook infrastructure.

The REST API approach is often simpler to start with because it requires no inbound webhook endpoint and works on the free TrustLens tier. The webhook approach adds real-time push notifications for serious events — a blocked customer opening a support ticket can be flagged before the agent starts the conversation.

Slack: real-time alerts for high-risk events

Slack’s Incoming Webhooks are one of the most straightforward integrations with TrustLens. Create a Slack app, enable Incoming Webhooks, get the webhook URL, and add it as a TrustLens endpoint subscribed to high_risk_order and customer_blocked.

The one complication is that Slack expects a specific JSON structure ({"text": "..."} or a Blocks array), and TrustLens sends its own payload format. You need a small adapter layer between the two. A Cloudflare Worker or AWS Lambda function works well here — receive the TrustLens payload, verify the signature, transform it to Slack’s format, and forward it to the Slack Incoming Webhook URL. Here is a minimal transformation example in Node.js:

// Adapter: TrustLens → Slack
function transformToSlack(payload) {
  const c = payload.customer;
  const emoji = c.segment === "critical" ? ":rotating_light:" : ":warning:";

  if (payload.event === "high_risk_order") {
    const o = payload.order;
    return {
      text: `${emoji} High-risk order placed`,
      blocks: [{
        type: "section",
        text: {
          type: "mrkdwn",
          text: `*Order #${o.number}* — ${o.currency} ${o.total}\n`
              + `Customer segment: *${c.segment}* (score: ${c.trust_score})\n`
              + `Return rate: ${c.return_rate}% over ${c.total_orders} orders`
        }
      }]
    };
  }

  if (payload.event === "customer_blocked") {
    return {
      text: `${emoji} Customer blocked`,
      blocks: [{
        type: "section",
        text: {
          type: "mrkdwn",
          text: `Customer (score: *${c.trust_score}*, segment: *${c.segment}*) blocked.\n`
              + `Reason: ${payload.reason || "not specified"}`
        }
      }]
    };
  }

  return { text: `TrustLens event: ${payload.event}` };
}

This pattern — TrustLens fires a webhook, a small adapter transforms the payload, the adapted payload goes to Slack — is also how you would integrate with PagerDuty for on-call escalations, with Linear for issue creation, or with any other tool that has an HTTP intake but expects its own payload schema.

Custom receivers: things to build right the first time

If you are writing a custom receiver rather than connecting to a specific SaaS tool, a few design decisions are worth getting right before you write the first line of production code:

• Idempotency. The X-TrustLens-Delivery header carries a unique UUID per delivery. If your receiver might process the same event twice (for example, after a restart or due to a retry), store this UUID and skip duplicates. TrustLens delivers non-blocking and non-retrying in production, but network issues at your infrastructure layer can result in duplicate processing.
• Fail fast on bad signatures. Return a 4xx response immediately if signature verification fails rather than processing the payload and then discarding it. This makes it obvious in the TrustLens delivery log that your receiver rejected the request and why.
• Return 2xx quickly. If your receiver needs to do significant work in response to an event (a database write, an API call to a third-party), do it asynchronously after returning the 200 response. TrustLens dispatches non-blocking and does not use the response to determine delivery success, but a slow receiver can accumulate in-flight requests under load.
• Handle the email hash vs. email tradeoff thoughtfully. The customer.email_hash is a stable pseudonymous identifier you can use to match customers across systems without storing raw emails. The customer.email field contains the plaintext address, which is more useful for CRM matching but has higher GDPR/privacy weight. Store only what you actually need for each destination.

REST API Reference (Free Tier)

TrustLens includes a REST API with 8 endpoints at the namespace /wp-json/trustlens/v1/. All endpoints require either the manage_woocommerce WordPress capability (for authenticated admin users) or a valid API key passed via the X-TrustLens-API-Key header. API keys are configured at TrustLens → Settings.

The full set of endpoints, verified against class-rest-api.php version 1.2.5:

The customer response object from a GET /customers/lookup call contains:

{
  "id": 412,
  "email_hash": "a3f2...64 chars",
  "trust_score": 34,
  "segment": "risk",
  "segment_label": "Risk",
  "total_orders": 12,
  "total_refunds": 5,
  "return_rate": 41.7,
  "total_order_value": 1380.00,
  "total_refund_value": 575.00,
  "is_blocked": false,
  "is_allowlisted": false,
  "first_order_date": "2025-03-12 09:14:00",
  "last_order_date": "2026-05-28 16:42:00",
  "created_at": "2025-03-12 09:14:00",
  "updated_at": "2026-06-04 11:07:00"
}

Pagination on list endpoints follows WordPress REST API conventions: X-WP-Total and X-WP-TotalPages headers in the response, with ?page=N&per_page=N query parameters. Maximum per_page is 100.

Automation Rule Webhooks vs. Settings Webhooks

TrustLens Pro has two distinct webhook mechanisms. Understanding the difference matters before you start connecting external systems, because they serve different purposes and have different delivery characteristics.

Settings webhooks (TrustLens → Settings → Webhooks) are always-on listeners that fire whenever one of the subscribed event types occurs. They fire on every matching event for every customer. They are the right tool for broad integrations: “send every high-risk order to this Slack channel,” “push every score update to this CRM endpoint.”

Automation Rule webhooks are actions in the Send Webhook action type within individual automation rules. They fire only when a specific rule’s trigger and conditions are met. They are the right tool for targeted, conditional notifications: “fire this webhook only when a customer in the Risk segment places an order with total above $200.” Rule webhooks also inherit the automation system’s cooldown window, deduplication, and retry logic, making them more reliable for high-stakes actions. For a full explanation of how Automation Rules work, including all 15 triggers and 10 actions, the guide on how TrustLens Automation Rules work covers the system in detail.

Both types use the same HMAC-SHA256 v2 signature scheme, so a receiver that validates the signature correctly works with both. The payload structure for Automation Rule webhooks includes the additional rule object with the rule’s name, ID, and trigger, plus the action field identifying the action that fired.

Frequently Asked Questions

Is the REST API available on the free version of TrustLens?

Yes. The full 8-endpoint REST API at /wp-json/trustlens/v1/ ships in the free version. It lets you look up customers, retrieve scores, filter by segment, update block/allowlist status, and trigger recalculations — all without a Pro license. Webhooks (the push-based delivery to external endpoints) are Pro-only. For a full comparison of what is included in free vs. Pro, the TrustLens free vs. Pro breakdown covers every feature tier.

Does TrustLens retry failed webhook deliveries?

This depends on which mechanism you are using. Settings webhooks fire non-blocking and do not automatically retry on failure — the delivery is logged but not re-queued. Automation Rule webhooks fire asynchronously via Action Scheduler and retry up to three times with exponential backoff: after 60 seconds, then 120, then 240. If reliable delivery for high-stakes events is important, Automation Rules are the right path.

What happens if my endpoint is temporarily down?

For Settings webhooks, deliveries during downtime are lost. TrustLens fires and logs; it does not queue for later. Design your receiver infrastructure accordingly — if you need guaranteed delivery, either use Automation Rule webhooks (which retry) or put a durable message queue (SQS, Cloud Pub/Sub) in front of your endpoint so deliveries land in the queue even if the downstream processor is down.

Can I scope a webhook to fire only for specific customers or segments?

Settings webhooks fire for all customers matching the event type — there is no per-segment filter at the endpoint level. To scope delivery to specific customers or conditions, use an Automation Rule with Send Webhook as the action and the relevant conditions (e.g. segment = Risk, trust_score < 30) applied to the rule. As described in the guide on using TrustLens Automation Rules for graduated fraud response, condition-scoped webhooks are a common pattern for routing different risk levels to different downstream systems.

How do I look up a customer in the REST API if I have their email but not their hash?

Use the GET /wp-json/trustlens/v1/customers/lookup?email={address} endpoint. This endpoint accepts a plaintext email address, hashes it internally using the same keyed HMAC scheme the plugin uses for storage, and returns the matching customer record. You never have to compute the hash yourself for API calls — only for signature verification on webhook receivers.

Does TrustLens send customer data to any external service by default?

No. TrustLens operates entirely within your WordPress installation. The only outbound connections TrustLens makes are ones you explicitly configure — webhooks you set up, Slack alerts you enable, scheduled reports you subscribe to. No customer data leaves your server unless you configure a destination. This is confirmed in the plugin’s readme and the data-handling documentation.