Skip to main content

​
What are credit-based rewards?

An in-product credit reward is a non-monetary reward that can incentivize users within the product itself. Instead of rewarding a referrer with cash, you can reward successful referrals with free credits for your product. Cello Referral conversion process four-step attribution flow overview diagram

​
How will your platform be notified about new credits?

Cello provides a service that notifies your platform when a new credit reward is issued to a specific product user. Notifications are delivered as webhooks via HTTPS with Basic Auth for authentication.

​
Webhook Implementation

​
Authentication

All webhook requests use HTTP Basic Auth:
  • Username: Will be provided by the Cello Support team.
  • Password: Will be provided by the Cello Support team.
Please always make sure HTTPS and reject requests without valid credentials.

​
Endpoint URL

The endpoint URL for the sandbox and prod environment should be shared during implementation to the Cello Support team. In the future, this can be managed inside the Cello Portal.

​
HTTP Request

  • Method: POST
  • Headers:
    • Authorization: Basic base64({username}:{password})
    • Content-Type: application/json; charset=utf-8
    • X-Cello-Env: prod | sandbox

​
Event Payload

{
  "version": "1.0.3",
  "eventType": "new-reward",
  "createdTs": "2024-07-20T12:34:56.789Z",
  "eventId": "evt_1Rl4G0KEzvleW5flVs9sMRrs",
  "data": {
    "rewardId": "rwd_7f3ac1e0",
    "productUserId": "your_product_user_id_9d1b3e2f",
	"rewardType": "credits",
    "reward": {
    	"amount": 500
    }
  }
}

​
Delivery Semantics

​
Retry Logic

Every event is delivered at least once. If the initial attempt fails, Cello’s platform performs multiple retries. Failed events will move to a failure queue after all retry attempts are exhausted.

​
Deduplication

  • eventId is stable per reward and should be used for deduplication, it will not change between retry attempts

​
Customer Responsibilities

The customer is responsible for a secure endpoint with Basic Auth and HTTPS. Ideally, events are processed asynchronously and deduplicated. The customer endpoint must respond with 2xx.

​
Versioning

Backward-compatible changes are added as minor/patch version bumps (e.g., 1.0.3 → 1.1.0).