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

# Credit-based Rewards

> Learn how to implement in-product credit rewards through webhooks

## 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.

<img src="https://mintcdn.com/cello/MtAEN0U39DXZmpIF/attribution/cello-rewards-credit-based-rewards.png?fit=max&auto=format&n=MtAEN0U39DXZmpIF&q=85&s=ac4c854dc46b80791f7558c034d9b048" alt="Cello Referral conversion process four-step attribution flow overview diagram" width="798" height="1000" data-path="attribution/cello-rewards-credit-based-rewards.png" />

## 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

```json theme={null}
{
  "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).