---
title: Webhook Payloads
description: "TrustLens delivers JSON payloads over two separate webhook paths, and they do *not* share a payload shape. This page documents the exact body and headers each one sends so receivers can be implemented against the real contract. - **Global webhook…"
url: "https://webstepper.io/docs/trustlens/developer-documentation/webhook-payloads/"
updated: "2026-10-18"
category: Developer Documentation
---

# Webhook Payloads

TrustLens delivers JSON payloads over two separate webhook paths, and they do *not* share a payload shape. This page documents the exact body and headers each one sends so receivers can be implemented against the real contract.

- **Global webhook endpoints** (Settings → Integrations → Webhooks, Pro) — fire on a fixed set of customer/order lifecycle events once **Enable Webhooks** is on (it's off by default). Flat payload, one shape per event.
- **Automation-rule webhooks** (the `send_webhook` action on a Pro automation rule) — fire whenever a rule with that action matches. Every one of these carries the same `trustlens_automation` envelope regardless of which trigger fired it.

---

## Global Webhook Events

Global endpoints emit exactly these event strings (the value of the top-level `event` field and the `X-TrustLens-Event` header):

| Event | Fires when |
| --- | --- |
| `score_updated` | A customer's trust score is recalculated |
| `customer_blocked` | A customer is blocked |
| `customer_unblocked` | A block is removed |
| `customer_allowlisted` | A customer is allowlisted |
| `customer_allowlist_removed` | An allowlist entry is removed |
| `checkout_blocked` | A checkout is blocked by enforcement |
| `high_risk_order` | An order is placed through checkout by a customer whose record is already in the `risk` or `critical` segment |
| `automation_triggered` | A row is written to the Pro automation log — a completed or failed action, but also a skipped evaluation (conditions not met, cooldown) or a queued webhook / hold. The payload doesn't say which |

The global "Events to Send" setting controls which events fire (`score_updated`, `customer_blocked`, `checkout_blocked`, `high_risk_order` out of the box). Endpoints added in the admin receive every selected event — the Add Webhook Endpoint form has a URL, an optional signing secret and an active switch, but no per-endpoint event list.

Global deliveries are fire-and-forget: TrustLens sends the POST (15-second timeout, redirects not followed) without waiting for the response and doesn't retry. Each send is recorded in `{prefix}trustlens_webhook_logs` (most recent 1,000) and listed under Recent Webhook Deliveries, but the receiver's response isn't captured.

---

## Global Webhook Envelope

Global payloads are **flat** — there is no nested `data` wrapper. Every global payload has at minimum:

```
{
  "event": "score_updated",
  "timestamp": "2024-03-15T12:00:00+00:00",
  "customer": { ... },
  "site": {
    "url": "https://store.example.com",
    "name": "Example Store"
  }
}
```

| Field | Description |
| --- | --- |
| event | Event ID (one of the strings in the table above) |
| timestamp | ISO 8601 string (`current_time('c')`) at dispatch |
| customer | Customer object (see below); empty object if the customer record can't be resolved |
| site | Origin store URL and name, added to every global payload |

Individual events add their own fields alongside these — documented per-event below.

### Headers (global)

- `Content-Type: application/json`
- `X-TrustLens-Event` — the event ID
- `X-TrustLens-Delivery` — a UUID, unique per delivery attempt
- `X-TrustLens-Webhook-ID` — the configured endpoint's ID
- `X-TrustLens-Timestamp` — Unix epoch at dispatch
- `X-TrustLens-Signature` — present only when the endpoint has a secret; format `sha256=hex...`

**Signature note:** the HMAC-SHA256 is computed over `timestamp + "." + raw_body` (not the body alone), so receivers should reconstruct the signing string from the `X-TrustLens-Timestamp` header value and the raw request body. Signing the timestamp lets you reject replays by checking the timestamp is recent (a 5-minute window is recommended).

---

## Customer Object

The `customer` object on global events contains:

```
"customer": {
  "email_hash": "...",
  "email": "...",
  "trust_score": 47,
  "segment": "caution",
  "total_orders": 12,
  "total_refunds": 3,
  "return_rate": 25.0,
  "is_blocked": false,
  "is_allowlisted": false
}
```

---

## Per-Event Payloads (Global)

### score_updated

```
{
  "event": "score_updated",
  "timestamp": "...",
  "customer": { ... },
  "new_score": 47,
  "new_segment": "caution",
  "site": { ... }
}
```

### customer_blocked

```
{
  "event": "customer_blocked",
  "timestamp": "...",
  "customer": { ... },
  "reason": "Manual block by admin",
  "site": { ... }
}
```

### customer_unblocked / customer_allowlisted / customer_allowlist_removed

```
{
  "event": "customer_unblocked",
  "timestamp": "...",
  "customer": { ... },
  "site": { ... }
}
```

These three carry only the standard envelope plus the `customer` object — no extra event-specific fields.

### checkout_blocked

```
{
  "event": "checkout_blocked",
  "timestamp": "...",
  "customer": { ... },
  "email": "customer@example.com",
  "site": { ... }
}
```

### automation_triggered

```
{
  "event": "automation_triggered",
  "timestamp": "...",
  "customer": { ... },
  "rule": {
    "id": "3f2b9c1e-…",
    "name": "Block critical at checkout",
    "trigger": "checkout_blocked"
  },
  "action": "block_customer",
  "order_id": 5432,
  "site": { ... }
}
```

`rule.id` is the rule's UUID. `order_id` is null when the action wasn't tied to an order. The run's status isn't included, so this event also fires for skipped evaluations — use the automation-rule webhook (below) or the REST API if you need to know an action actually ran.

### high_risk_order

```
{
  "event": "high_risk_order",
  "timestamp": "...",
  "customer": { ... },
  "order": {
    "id": 5432,
    "number": "5432",
    "total": 159.99,
    "currency": "USD",
    "status": "pending"
  },
  "site": { ... }
}
```

Only sent when the ordering customer is in the `risk` or `critical` segment; orders from healthier segments never fire this event. It's sent when the order is placed through the classic or block checkout, before payment, so `status` is usually `pending`. Orders created in the admin or via the REST API don't fire it.

---

## Automation-Rule Webhooks

The `send_webhook` action on a Pro automation rule posts a single, fixed envelope. The `event` is always `trustlens_automation` — the specific trigger that fired the rule is carried in the `trigger` field, *not* in `event`. There is no per-trigger payload variation and no nested `data` wrapper.

```
{
  "event": "trustlens_automation",
  "rule": "Block critical at checkout",
  "rule_id": "3f2b9c1e-…",
  "trigger": "checkout_blocked",
  "email_hash": "...",
  "trust_score": 18,
  "segment": "critical",
  "fired_at": "2024-03-15 12:00:00",
  "attempt": 1
}
```

| Field | Description |
| --- | --- |
| event | Always the literal `trustlens_automation` |
| rule, rule_id | Name and ID (a UUID string) of the rule whose `send_webhook` action fired |
| trigger | The automation trigger key that matched (e.g. `checkout_blocked`, `score_updated`, `chargeback_filed`) |
| email_hash | Target customer's email hash |
| trust_score, segment | Current score/segment at fire time; null if the customer can't be resolved |
| fired_at | Local MySQL datetime at dispatch |
| attempt | 1 on first try; increments on each retry (up to 4) |
| refund_context | Only on rules with the `refund_processed` trigger: an object with the refund's amount, ratio, type, classification, reason, currency, transition, delivery evidence and the other refund fields |

### Headers (automation)

- `Content-Type: application/json`
- `X-TrustLens-Event: trustlens_automation`
- `X-TrustLens-Delivery` — a UUID per attempt
- `X-TrustLens-Rule-ID` — the rule ID
- `X-TrustLens-Timestamp` — Unix epoch at dispatch
- `X-TrustLens-Signature` — `sha256=hex...`, signed by default with the per-install automation secret (overridable via the `trustlens/automation/webhook_secret` filter)

Automation webhooks are queued with Action Scheduler, then sent as a blocking request (10-second timeout, redirects not followed) with up to 3 retries on non-2xx (60s / 120s / 240s backoff). See [Async Dispatch & Retries](/docs/trustlens/automation/async-dispatch-retries/) for the full retry model.

---

## Field Type Notes

- **Timestamps:** global payloads use an ISO 8601 string in `timestamp`; automation payloads use a local MySQL datetime in `fired_at`; both signature schemes use the Unix epoch from the `X-TrustLens-Timestamp` header.
- **Monetary amounts:** decimal numbers (not strings).
- **Hashes:** lowercase hex email hashes.
- **Enums:** lowercase strings matching the database/segment values.

---

## Backward Compatibility

Receivers should:

- Ignore unknown fields (forward-compatible)
- Not depend on field order (JSON objects are unordered)
- Handle missing fields gracefully (e.g. an empty `customer` object when the record can't be resolved)

Breaking changes to payloads are rare and announced in the changelog. Minor additions happen routinely.

---

## Testing

For testing receivers without waiting for real events, click **Test** next to an endpoint in Settings → Integrations → Webhooks. It sends `{"event": "test", "timestamp": …, "message": "This is a test webhook from TrustLens.", "site": {…}}` with `Content-Type`, `X-TrustLens-Event: test`, `X-TrustLens-Timestamp` and — when the endpoint has a secret — `X-TrustLens-Signature` (no Delivery or Webhook-ID header), and reports whether your receiver answered with a 2xx. Use it to verify your receiver's parsing and signature verification end to end.

Automation-rule webhooks have no test button; point a rule at a request-inspection tool such as webhook.site and trigger it.
