> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lexq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

> Connect LexQ to external services for coupon issuance, point systems, notifications, and webhooks.

## What are Integrations?

**Integrations** connect LexQ to your external services. When a rule's action fires, LexQ can call your coupon system, point platform, notification service, or any webhook endpoint.

Integrations are configured once and then referenced in rule actions by their ID.

## Integration Types

| Type           | Description                        | Use Case                             |
| -------------- | ---------------------------------- | ------------------------------------ |
| `WEBHOOK`      | Call any HTTP endpoint             | Order processing, custom logic       |
| `COUPON`       | Issue coupons via external service | Welcome coupons, seasonal promotions |
| `POINT`        | Award or deduct points             | Loyalty programs, cashback           |
| `NOTIFICATION` | Send SMS, email, or push           | Order confirmations, alerts          |
| `CRM`          | Sync user data or tags             | Customer segmentation                |
| `MESSENGER`    | Send messages via chat platforms   | Customer support automation          |

<Info>
  Integration types are **categories of external services** — they are independent of action types. The mapping from an action to an integration type is determined by the dispatcher, not by the action name.
</Info>

## Creating an Integration

### Console

Navigate to **Management → Integrations → Create Integration**, select the type, and fill in the configuration.

### CLI

```bash theme={null}
lexq integrations save --json '{
  "type": "WEBHOOK",
  "name": "Order Processing Webhook",
  "baseUrl": "https://api.example.com/webhooks/orders",
  "isActive": true
}'
```

### Check Required Configuration

Each type requires different configuration fields. Check what's needed:

```bash theme={null}
lexq integrations config-spec --type WEBHOOK
lexq integrations config-spec --type COUPON
```

## Using Integrations in Rules

LexQ engine actions are **domain-agnostic primitives** — see [Action Types](/guides/policy-rules#action-types) for the full reference. The patterns below show how each integration type is invoked.

### Coupon issuance — `EMIT_EVENT` + `COUPON` integration

```json theme={null}
{
  "type": "EMIT_EVENT",
  "parameters": {
    "integrationId": "<your-coupon-integration-id>",
    "eventPayload": {
      "couponId": "WELCOME_10"
    }
  }
}
```

The dispatcher routes `EMIT_EVENT` to a service registered for the integration's type. The integration provider is responsible for interpreting the `eventPayload` — the engine does not validate or transform its keys.

### Notification — `EMIT_NOTIFICATION` + `NOTIFICATION` integration

```json theme={null}
{
  "type": "EMIT_NOTIFICATION",
  "parameters": {
    "integrationId": "<your-notification-integration-id>",
    "targetVar": "phone_number",
    "notificationPayload": {
      "channel": "SMS",
      "templateId": "ORDER_CONFIRM"
    }
  }
}
```

`targetVar` identifies the recipient fact (`phone_number`, `email`, `device_token`, etc.). `notificationPayload` is passed through to the integration provider unchanged.

### Webhook — `EMIT_WEBHOOK` + `WEBHOOK` integration

```json theme={null}
{
  "type": "EMIT_WEBHOOK",
  "parameters": {
    "url": "<your-webhook-integration-id>",
    "method": "POST",
    "payloadTemplate": {
      "text": "Rule {{ruleName}} matched — {{fact.customer_tier}} customer, amount: {{output.payment_amount}}"
    }
  }
}
```

The `payloadTemplate` field is optional. When omitted, all facts are sent as the request body. When provided, only the template structure is sent with `{{variables}}` replaced by actual values. See [Policy Rules — EMIT\_WEBHOOK](/guides/policy-rules#emit_webhook--with-payload-template) for the full template variable reference.

### Point award — `INCREMENT_FACT`

For loyalty point awards, use `INCREMENT_FACT` to mutate the engine-side fact:

```json theme={null}
{
  "type": "INCREMENT_FACT",
  "parameters": {
    "targetVar": "total_point",
    "refVar": "payment_amount",
    "method": "PERCENTAGE",
    "rate": 1
  }
}
```

`generatedVariables.total_point__delta` exposes the increment that was applied (e.g., `1000` for a 1% rate on `payment_amount: 100000`).

<Info>
  Among engine actions, only `EMIT_WEBHOOK` performs in-engine variable substitution (via `payloadTemplate`). For `EMIT_EVENT` and `EMIT_NOTIFICATION`, payload values are passed through to the integration provider as-is — substitution and interpretation are the provider's responsibility.
</Info>

## Managing Integrations

```bash theme={null}
lexq integrations list
lexq integrations get --id <integrationId>
lexq integrations save --json '{...}'
lexq integrations delete --id <integrationId>
```

## Failure Handling

When an integration call fails during execution (network timeout, 5xx response, etc.), the failure is recorded in the **Failure Log**. You can retry, skip, or resolve failures:

```bash theme={null}
lexq logs list --status PENDING
lexq logs action --id <logId> --action RETRY
```

<Info>
  During Impact Simulations, integration calls are always mocked. In Dry Runs, mocking is controlled by the **Mock External Calls** toggle in the Console (API parameter: `mockExternalCalls`, default: `true`). When set to `false`, the engine attempts real calls — if they fail, entries are written to the Failure Log.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Policy Rules" icon="list-check" href="/guides/policy-rules">
    Learn how to use integrations in rule actions.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/help/troubleshooting">
    Common integration issues and solutions.
  </Card>
</CardGroup>