🚀 Reward custom events in your portal

Incoming events let you reward actions that happen outside of Qualifio, such as on your website, mobile app, CRM, or other external tools.

They are a simple way to:

• Reward members for real-world actions
• Increase engagement
• Get richer insights into your audience

With just a few steps, you can connect your external systems to your loyalty program.

Creating incoming events

Incoming events use a secure API endpoint to send member actions into the platform. These actions can be:

• Reading an article
• Watching a video
• Completing a purchase
• Visiting a store
• Clicking an email CTA
• Finishing a survey

When an event is sent, it can then trigger points allocation through earning rules.

Setting up an incoming event

Go to Settings > Incoming Events, click + New incoming event

1. Enter a clear name (e.g. Article Read)
2. Select and define authentication method
3. Select the corresponding event type it should trigger
   • Use "Custom > Basic" as event type for 100 % flexibility 
   • Use "Ecommerce > Purchase" to proxy ou purchase events
   • Both standard versions are documented here.
4. Complete the mapping section for your payload
5. Save

Once created, the connector gives you a unique endpoint URL to target (see 5 on screenshot). This information should be shared with your developers.

Step 2: Authenticating incoming events

Each event must be authenticated with a token to be processed via your dedicated endpoint. You decide the method:

• Add a token as a query parameter
• Add a token as a header (e.g. X-Authorization)
• Use a hub signature with a secret

🔒 Only requests with the correct token will be accepted.

Step 4: Mapping your data

External systems send data in different formats. To make it compatible, you map your payload using JSONata.

Mapping lets you:

• Identify the user
• Convert timestamps
• Add tags (text criteria)
• Add counters (numeric criteria)

Example mapping:

{
  "clientEventId": eventId,
  "profile": { "kind": "default", "value": profile.email },
  "payload": {
    "timestamp": timestamp,
    "tags": [ { "name": "theme", "value": article.theme } ],
    "counters": [ { "name": "total", "value": totalArticlesRead } ]
  }
}

Once mapped, the tags and counters are made available as criteria in the earning rules.

👉 Our Solutions Architects can support you with JSONata mapping. Feel free to reach out at integrations@qualifio.com.

Creating earning rules

When creating an earning rule:

• Select Custom as the source
• Choose your incoming event from the dropdown eg "Articles Read"

Criteria available in rules:

• Tags → text criteria (e.g. theme in above example)
• Counters → numeric criteria (e.g. total in above example)

Testing your event

You can send test events via:

• Scripts or backend systems
• Customer Data Platforms (CDPs)
• CRM or ESP webhooks
• Tag managers

Every request must include:

• The endpoint URL
• The token
• A valid JSON payload

Events can be sent individually or in batches. Tests will allow you to:

• Validate the mapping
• Check the profile identifier resolution
• Simulate earning rules

🧪 Tests are safe — data is saved but can easily be cleared out before a launch thanks to our purge mechanism.

Monitoring & troubleshooting

Each incoming event is logged and traceable. You can check:

• Member profiles (activity history)
• Event logs

⚠️ Events missing a valid identifier are ignored. Use the logs to debug.

Good to know

• Bulk events: Supported with arrays
• Payload size: Contact your account manager for limits
• Latency: Rewards appear in seconds
• Propagation: Member profile updates are real-time