Integration via Segment

Wecheer uses Segment as its outbound event delivery middleware. When users interact with your campaign, Wecheer streams real-time events into your Segment workspace — from there you can route data to your CRM, CDP, analytics tools, and more.

Why Segment?

• Industry standard for event routing
• 450+ pre-built integrations
• Highly secure and SOC 2 compliant
• Zero additional cost for Wecheer clients

Integration Methods

Event Categories

Wecheer emits three categories of events. See the Event Scheme section for full schemas.

Integration via Segment Source

The Segment Source integration is the recommended approach for most clients. Wecheer will be onboarded as a Source in your Segment workspace and will automatically forward all campaign events in real time.

How It Works

Setup Steps

The full step-by-step setup guide is published and maintained by our team in the official Segment catalog documentation.

Common CRM & Marketing Destinations

Once Wecheer is connected as a Segment Source in your workspace, you can route events to any destination available in the Segment Catalog — with no additional development required on your side. Below are the most common platforms enterprise clients connect to.

Example: Connecting HubSpot

HubSpot is available as a native destination in the Segment Catalog. Once Wecheer is set up as a Source in your workspace, connecting HubSpot takes only a few minutes and requires no code changes.

Integration via Segment Custom Function

Use a Segment Custom Function when you need to transform Wecheer events before forwarding them, or when your destination system is not available in the Segment catalog.

When to Use This Approach

• Your destination system is not in the Segment catalog
• You need to transform or enrich event payloads before forwarding
• You want to apply conditional routing logic (e.g. send only certain event types)
• You need to merge Wecheer data with data from other sources

How It Works

A Segment Function is a small JavaScript function that runs in Segment's cloud infrastructure. It receives incoming Wecheer events, applies your custom logic, and forwards the processed data to your endpoint.

Setup Steps

async function onTrack(event, settings) {
  const payload = {
    eventName: event.event,
    userId: event.userId,
    timestamp: event.timestamp,
    properties: event.properties
  };

  const response = await fetch(settings.destinationUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${settings.apiToken}`
    },
    body: JSON.stringify(payload)
  });

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }
}

Integration Responsibilities

Getting your integration live is a team effort — and we've made our part as lightweight as possible. Here's a clear picture of what Wecheer handles, what you'll own, and how we'll have your back every step of the way.

Our Philosophy

We built our integration around a simple idea: your data environment is yours. Whether Wecheer is sending events into your tools or your platform is sending events into ours, you stay in full control — of your credentials, your data schema, and your business logic. No external party needs access to your internal systems.

Our role is to make the setup fast and the testing safe. We provide everything your team needs to move quickly — documentation, schemas, credentials, and a sandbox — so that by the time you go live, there are no surprises.

Send Events from Wecheer

This covers the outbound flow: Wecheer campaign events (reward earned, stamp received, user registered, etc.) flowing into your CRM, marketing platform, or data warehouse via Segment.

Via Segment Source Recommended

Via Segment Custom Function

Send Events to Wecheer

This covers the inbound flow: your platform sending purchase, scan, or engagement events into Wecheer via our API to trigger points, stamps, and rewards in real time.

Via API

Need a Hand? We've Got You.

If your team is stretched thin or you'd rather have us handle the heavy lifting, Wecheer offers hands-on implementation support through our paid Professional Services offering.

Just let your Wecheer account manager know and we'll put together a proposal that fits your timeline and scope.

At a Glance

Event Scheme

Wecheer emits three categories of Segment events. All events follow the standard Segment track structure with Wecheer-specific properties.

Base Event Structure

{
  "type": "track",
  "event": "EventName",
  "userId": "user-uuid-12345",
  "timestamp": "2026-01-15T12:34:56.789Z",
  "properties": { },
  "context": { "source": "wecheer", "version": "1.0" }
}

Consumption Events

Events triggered by product scans, purchases, and reward-earning activities.

Example: points_received

{
  "type": "track",
  "event": "points_received",
  "userId": "user-uuid-12345",
  "timestamp": "2026-01-15T12:34:56.789Z",
  "properties": {
    "eventId": "evt-uuid-12345",
    "campaignId": "camp-12345",
    "points": 150,
    "reason": "product_scan",
    "previousBalance": 1000,
    "newBalance": 1150
  }
}

User Events

Events related to user registration, profile updates, and data sharing.

Example: user_created

{
  "type": "track",
  "event": "user_created",
  "userId": "user-uuid-12345",
  "properties": {
    "email": "[email protected]",
    "phone": "+1234567890",
    "registrationSource": "campaign_link",
    "campaignId": "camp-12345",
    "marketingConsent": true
  }
}

Reward Events

Events for reward catalog and redemption activities.

Example: CatalogRedeem

{
  "type": "track",
  "event": "CatalogRedeem",
  "userId": "user-uuid-12345",
  "properties": {
    "redemptionId": "redeem-uuid-12345",
    "rewardId": "reward-uuid-12345",
    "rewardName": "Coffee Voucher",
    "cost": { "points": 500 },
    "voucherCode": "COFFEE-ABC123"
  }
}

Integration via API (Webhook)

What to Expect

The Webhook integration will allow Wecheer to deliver outbound events directly to an HTTP endpoint of your choice — without requiring a Segment workspace. This is ideal for clients who prefer direct server-to-server communication or have specific infrastructure requirements that make Segment impractical.

Integration via Segment Destination

What to Expect

The Segment Destination integration will allow you to send events to Wecheer directly from your existing Segment workspace — using your existing Segment tracking infrastructure. Instead of integrating with the Wecheer API directly, you will simply add Wecheer as a Destination in Segment and route the relevant events.

User Conditions for Receiving Rewards

Before a user can receive rewards through the Wecheer platform, the following conditions must be met.

1. Campaign Participation

The user must join a campaign to be eligible for rewards.

2. Unique Consumption

The consumption event must not have been previously processed. This is verified using the consumptionId, which must be unique for each consumption.

3. User Status

The user must not be blocked on the Wecheer side.

Authorize Endpoint

Used to authenticate the client and provide a token that authorizes requests to other endpoints.

curl -X 'POST' \
  'https://api.wecheer.me/staging-usermanagement/api/advertiser/v1/authorize' \
  -H 'accept: text/plain' \
  -H 'apiKey: 7f2156c3-d398478b-854632efc7cade1b' \
  -H 'apiSecret: 3DpcdDQca8p3lZXQ1BoNBiGNlA3ZnCFjZYstElG0WHVMv13E87mrYPXdMj4hgIsM' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
  "advertiserId": "1000112586"
}'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcGlLZXkiOiI3ZjIxNTZjMy1kMzk4LTQ3OGItODU0Ni0zMmVmYzdjYWRlMWIiLCJhZHZlcnRpc2VySWQiOiIxMDAwMTEyNTg2IiwibmFtZSI6IkJBVCBTdGFnaW5nIiwibmJmIjoxNzYwNjg3MDA4LCJleHAiOjE3NjA2OTA2MDgsImlhdCI6MTc2MDY4NzAwOCwiaXNzIjoid2VjaGVlci5pbyIsImF1ZCI6Imh0dHBzOi8vd2VjaGVlci5pbyJ9.v9-yRVhxk3lk8BdLycGfsrkhdv153Z22uRnYcE8NJP8",
  "advertiserId": "1000112586"
}

Consumption Endpoint

Used to process dynamic events based on configured SKUs from the platform, synthetically created to reflect user actions. For example, custom actions done by users in the client system that should trigger a reward.

{
  "consumptionId": "I198037776491223",
  "consumptionDate": "20250425T12:34:00Z",
  "identifiers": [
    {
      "key": "phoneNumber",
      "value": "40720005123"
    },
    {
      "key": "email",
      "value": "[email protected]"
    }
  ],
  "consumptionLines": [
    {
      "sku": "velo_pk_poll_strength",
      "quantity": 1
    }
  ]
}

curl -X 'POST' \
  'https://api.wecheer.me/staging-campaigns/api/advertiser-integration/v1/consumption' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
  "consumptionId": "I198037776491223",
  "consumptionDate": "20250425T12:34:00Z",
  "identifiers": [
    {
      "key": "phoneNumber",
      "value": "40720005123"
    },
    {
      "key": "email",
      "value": "[email protected]"
    }
  ],
  "consumptionLines": [
    {
      "sku": "velo_pk_poll_strength",
      "quantity": 1
    }
  ]
}'

Integration via API

Send events directly to Wecheer using the Inbound API. This is the primary integration method for triggering rewards, processing user actions, and syncing data from your systems to the Wecheer platform.

Available Endpoints

Quick Reference

API Endpoints

Base URLs

Use Cases

Status Codes & Errors

HTTP status codes and error responses from the Wecheer API.

HTTP Status Codes

Common Error Codes

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": { }
  }
}

Rate Limits

API throttling policies and best practices for handling limits.

Rate Limit Headers

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1705320000

Handling Rate Limits

async function requestWithBackoff(fn, maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fn();
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await sleep(retryAfter * 1000);
      continue;
    }
    
    return response;
  }
}

Security & Compliance

Enterprise-grade security practices and certifications.

Infrastructure Security

SSL Ratings

Compliance

Fraud Prevention

• reCAPTCHA Enterprise
• Phone verification (SMS OTP)
• Velocity checks and rate limiting
• Pattern detection
• Duplicate detection

Glossary

Definitions of key terms used throughout the Wecheer platform.