External Integrations

Connect loyalty, gamification, engagement, and rewards platforms to Retivo's intelligence engine

External integrations let other platforms plug into Retivo's decision engine. Retivo provides the intelligence (who needs what, when, and why), and the external system provides the execution (granting points, unlocking badges, managing tiers).

How It Works

External System                              Retivo
     │                                          │
     ├── POST /external/action-types ──────────► Register capabilities
     │                                          │
     ├── POST /external/events ────────────────► Push events
     │                                          │
     │◄── Webhook: action dispatch ─────────────┤ Retivo sends action
     │                                          │
     ├── POST /external/actions/:id/outcome ───► Report result
     │                                          │
     ├── POST /decisions/recommend ────────────► Ask for intelligence
     │◄── { action, parameters, confidence } ───┤ Get recommendation

1. Register Action Types

Tell Retivo what your system can do. Each action type has a name, parameter schema, and a webhook URL where Retivo will dispatch actions.

curl -X POST https://retivo.ai/api/external/action-types \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "grant_points",
    "description": "Award loyalty points to user",
    "provider": "loyalty-platform",
    "parameters_schema": {
      "amount": { "type": "number", "required": true },
      "reason": { "type": "string" }
    },
    "delivery_webhook": "https://loyalty.app/api/retivo/actions",
    "domain": "loyalty"
  }'

The response includes a webhook_secret for verifying HMAC signatures. Store it securely — it's only returned once.

{
  "action_type": {
    "id": "at_abc123",
    "name": "grant_points",
    "webhook_secret": "64-char-hex-secret",
    ...
  }
}

2. Receive Dispatched Actions

When Retivo's decision engine determines a user should receive an action, it sends a POST to your delivery_webhook:

{
  "action_id": "ea_xyz789",
  "action_type": "grant_points",
  "user_id": "user-123",
  "parameters": {
    "amount": 500,
    "reason": "re-engagement bonus"
  },
  "reasoning": "User hasn't been active for 14 days but completed onboarding successfully",
  "confidence": "0.82",
  "tenant_id": "tenant-uuid",
  "timestamp": "2026-04-26T10:30:00Z"
}

Verify Signatures

Every dispatch is signed with HMAC-SHA256. Verify using the webhook_secret from registration:

import crypto from 'node:crypto';

function verifyRetivo(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// In your handler:
const rawBody = await request.text();
const signature = request.headers.get('X-Retivo-Signature');
if (!verifyRetivo(rawBody, signature, WEBHOOK_SECRET)) {
  return new Response('Invalid signature', { status: 401 });
}

Headers included on every dispatch:

X-Retivo-Signature — HMAC-SHA256 hex digest
X-Retivo-Timestamp — ISO-8601 dispatch time
X-Retivo-Action-Id — unique action ID for idempotency

Retry Behavior

Failed dispatches (non-2xx or timeout) are retried with exponential backoff: 30s → 2m → 10m → 30m → 2h (5 retries max). After all retries, the action is marked as failed.

3. Report Outcomes

After executing the action, tell Retivo what happened. This closes the feedback loop so Retivo learns which actions work.

curl -X POST https://retivo.ai/api/external/actions/ea_xyz789/outcome \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "result": {
      "points_granted": 500,
      "user_reacted": true,
      "next_action_within": "2h"
    }
  }'

Outcome statuses:

Status	Meaning
`completed`	Action was executed and user engaged
`partial`	Action executed but user didn't fully engage
`ignored`	Action delivered but user took no action
`rejected`	Action couldn't be executed (e.g., user ineligible)

4. Push Custom Events

Send events from your system into Retivo's data pipeline. These events feed the decision engine — "user who just redeemed a reward is less likely to churn" becomes a learnable signal.

curl -X POST https://retivo.ai/api/external/events \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "custom.reward.redeemed",
        "user_id": "user-123",
        "data": {
          "reward_type": "discount",
          "value": 20,
          "currency": "USD"
        }
      },
      {
        "type": "custom.badge.unlocked",
        "user_id": "user-456",
        "data": { "badge": "power_user" }
      }
    ]
  }'

Event types must use the custom. prefix with lowercase dot notation (e.g., custom.reward.redeemed, custom.tier.upgraded).

5. Ask for Recommendations

Pull-based integration: ask Retivo "what should I do for this user right now?"

curl -X POST https://retivo.ai/api/decisions/recommend \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "domain": "loyalty",
    "available_actions": ["grant_points", "unlock_badge", "upgrade_tier"],
    "context": {
      "current_points": 1200,
      "current_tier": "silver",
      "days_since_last_redemption": 14
    }
  }'

Response:

{
  "user_id": "user-123",
  "domain": "loyalty",
  "recommendation": {
    "action": "grant_points",
    "parameters": { "amount": 300, "reason": "re-engagement bonus" },
    "confidence": 0.82,
    "reasoning": "User hasn't redeemed in 14 days but completed onboarding. Similar users respond to point grants."
  },
  "alternatives": [
    {
      "action": "unlock_badge",
      "parameters": { "badge": "comeback_king" },
      "confidence": 0.65,
      "reasoning": "Badge unlock has lower confidence but higher novelty"
    }
  ],
  "user_context": {
    "lifecycle_stage": "active",
    "activation_score": 72,
    "engagement_score": 45,
    "risk_level": "medium"
  }
}

6. Pull Reconciliation

If a webhook dispatch fails, your system can pull missed actions:

curl "https://retivo.ai/api/external/actions?status=dispatched&since=2026-04-25T00:00:00Z" \
  -H "Authorization: Bearer rt_live_..."

Filter by status (pending, dispatched, completed, failed, expired), provider, user_id, or since timestamp.

Event	When
`external_action.dispatched`	Action sent to external system
`external_action.completed`	External action reported success
`external_action.failed`	External action failed or rejected
`custom.*`	Any custom event from external systems

Configure subscriptions in Settings > Webhooks or via the API.

Pre-Built Connectors

Retivo has pre-built connectors for popular platforms. Instead of manually registering action types, connect with one click in Settings > Integrations > Action Platforms:

Platform	Category	Actions Auto-Registered
Smile.io	Loyalty	grant_points, upgrade_vip_tier, issue_reward
LoyaltyLion	Loyalty	grant_points, create_reward
Talon.One	Loyalty	grant_points, apply_coupon, update_tier
Gameball	Gamification	grant_points, send_challenge, unlock_badge
Customer.io	Engagement	trigger_campaign, send_push
Yotpo	Rewards	grant_points, create_coupon
Rivo	Rewards	grant_points, issue_discount

Or use the API:

# List available platforms
curl https://retivo.ai/api/external/platforms \
  -H "Authorization: Bearer rt_live_..."

# Connect a platform (auto-registers action types)
curl -X POST https://retivo.ai/api/external/platforms/smile-io/connect \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "credentials": { "api_key": "sk_live_..." } }'

Partner Integration (B2B2C)

If you're a platform that wants to embed Retivo's intelligence for your customers, use the Partner API.

Become a Partner

Provision customer tenants — each of your merchants/users gets their own Retivo instance
Share integrations — configure action types once, automatically applied to all customers
Query across customers — aggregate intelligence across your customer base

Provision a Customer

curl -X POST https://retivo.ai/api/partners/customers \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Merchant ABC",
    "slug": "merchant-abc",
    "plan_tier": "growth",
    "tracked_user_limit": 5000
  }'

The response includes an API key for the customer tenant. Your platform uses this key to track events and receive decisions on behalf of the merchant.

# Register your integration
curl -X POST https://retivo.ai/api/partners/integrations \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "your-platform",
    "display_name": "Your Platform",
    "domain": "loyalty",
    "action_type_templates": [
      {
        "name": "grant_points",
        "description": "Award loyalty points",
        "parameters_schema": { "amount": { "type": "number" } },
        "delivery_webhook": "https://your-platform.com/api/retivo/dispatch"
      }
    ]
  }'

# Share with a customer
curl -X POST https://retivo.ai/api/partners/integrations/{id}/share \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "customer_tenant_id": "tenant-uuid" }'

When you provision new customers, active partner integrations are automatically shared.

External Integrations

On this page