Callback

Callback is the reward fulfillment mechanism used by Enable3 during reward redemption.

It is not a generic webhook. Callback is triggered when a user redeems a reward inside Enable3, and the final reward outcome must be produced by the administrator's system.

The callback connects Enable3’s internal reward lifecycle with the administrator's fulfillment logic:

User → Redeem Reward → Enable3 → Callback → Admin → Result → Enable3 → User

• Enable3 manages the redemption process, including balance handling, reward state, retries, and result storage.

• The administrator's backend is responsible for fulfilling the reward by generating or applying the actual outcome, such as a promo code, bonus, gift card, or external reward.

When Callback Is Used

Callback is triggered after a reward redemption request has passed Enable3 validation.

It is used when a reward requires admin-side fulfillment, including:

• Generating unique promo codes

• Applying bonuses in the administrator's system

• Creating rewards through third-party providers

• Performing admin-specific business validation

• Producing the final reward payload returned to the user

If a reward is fully managed within Enable3 and does not require external fulfillment, the callback is not involved.

Reward Redemption Flow

1. User redeems a reward The user initiates reward redemption through the widget, SDK, or API.

2. Enable3 validates the request Enable3 verifies:

   • User balance

   • Reward availability

   • Redemption eligibility

3. Enable3 creates a redemption request A stable request identifier is generated, and the redemption enters processing state.

4. Enable3 triggers the callback The administrator backend receives a fulfillment request with all required data.

5. The admin's system processes the request Depending on the reward type, the administrator:

   • Generates a promo code

   • Applies a bonus

   • Calls external systems

   • Executes business validation

   • Produces the final reward payload

6. The admin's system returns the fulfillment result The response indicates success or failure.

7. Enable3 finalizes the reward Enable3:

   • Stores the result

   • Updates redemption status

   • Returns the final outcome to the user

Responsibilities

Enable3

Enable3 is responsible for the reward lifecycle and system integrity:

• Reward availability validation

• User balance validation and deduction

• Redemption request creation and tracking

• Callback triggering

• Retry handling for failed or timed-out callbacks

• Idempotency enforcement via request identifier

• Storing fulfillment results

• Returning final reward outcome to the user

Enable3 owns the reward state and consistency guarantees.

Administrator

The administrator is responsible for reward fulfillment:

• Generating the final reward outcome

• Applying rewards in internal systems

• Integrating with third-party providers

• Performing business-specific validation

• Returning success or failure result

• Handling duplicate requests idempotently

The admin owns the execution of the reward outside Enable3.

Callback Contract (Conceptual)

The callback request provides all information required for fulfillment.

Request contains

• User identifier Enable3 user ID and/or admin user ID

• Reward identifier The reward being redeemed

• Reward type Defines fulfillment logic (e.g. PROMO_CODE, BONUS, EXTERNAL)

• Request identifier (idempotency key) A stable unique identifier used across retries

• Reward metadata Configuration required for fulfillment

Response must indicate

• Success Reward fulfilled Includes final payload returned to the user (e.g. promo code, confirmation, external reference)

• Failure Reward not fulfilled Includes a clear failure reason

Failure Handling and Retries

Callback execution is not guaranteed to succeed on the first attempt.

Possible failure scenarios

• Network errors

• Timeouts

• Admin backend issues

• Third-party provider failures

• Invalid fulfillment requests

• Unexpected responses

Enable3 applies a retry policy for failed or timed-out callbacks.

Idempotency Requirement

Retries may result in the same request being delivered multiple times.

The admin must implement idempotent handling:

• The same request identifier must not create multiple rewards

• The admin should store the request identifier

• Repeated requests must return the same result

Timeout Behavior

If the admin does not respond in time:

• Enable3 treats the attempt as failed or pending

• A retry may be triggered

Important:

• Timeout does not cancel the reward

• If fulfillment completes after timeout, subsequent retries must return the same result

Permanent Failure

If fulfillment cannot be completed after retries:

• Enable3 marks the redemption as failed

• The failure reason is stored

• The user does not receive a reward payload

Balance and reward state are handled according to Enable3 lifecycle rules.

Reward Types

Callback behavior depends on the reward type.

PROMO_CODE

• Administrator generates or retrieves a code

• Enable3 stores and displays it to the user

BONUS

• Administrator applies bonus in internal system

• Response confirms successful application

EXTERNAL

• Administrator fulfills reward via external provider

• Example providers include gift cards, Shopify, or third-party services

• Response includes final external reference or payload

Request body example:

{ 
  "userId": "14813ccc-83b6-11ee-b962-0242ac120002", 
  "optionId": "97cf7320-25f0-485d-a2c9-2ae60c05574e",
  "purchaseProductId": "product123", 
  "amount": 100.00, 
  "tokenAmount": 500.00,
  "tokenRate": 5.0,
  "transactionId": "709a45bd-2b9a-452d-9ae2-a9aa479c29e6",
  "createdAt" : "2024-05-30T12:14:40.988257"
}

Body

Name	Type	Mandatory	Description
userId	String	Yes	Unique user ID on the application side
optionId	String	No	This field will be empty in case of custom withdrawal
purchaseProductId	String	No	Custom value that can be assigned in the Admin dashboard
amount	Number	Yes	Amount in USDC
tokenAmount	Number	Yes	Amount in tokens
tokenRate	Number	Yes	Token rate
transactionId	String	Yes	Unique transaction ID from Enable3. Available in the Admin dashboard
createdAt	String	Yes	Date and time when the user requested withdrawal. Format: yyyy-MM-dd'T'HH:mm:ss.SSSSSS

The callback request will be signed and contains X-REQUEST-SIGNATURE header.

An example of how to get the signature of the request body using secret:

For Java

public String getSignature(String requestBody, String secret) {
    String md5Hex = DigestUtils.md5Hex(requestBody);
    try {
        Mac shaHMAC = Mac.getInstance("HmacSHA512");
        SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(), "HmacSHA512");
        shaHMAC.init(secretKey);
        return Base64.getEncoder().encodeToString(shaHMAC.doFinal(md5Hex.getBytes()));
    } catch (GeneralSecurityException ex) {
        log.error(ex.getMessage(), ex);
        throw new RuntimeException("Request signing error", ex);
    }
}

For Node JS

const crypto = require('crypto');
function getSignature(requestBody, secret) {
  const md5Hex = crypto.createHash('md5').update(requestBody).digest('hex');
  const hmac = crypto.createHmac('sha512', secret);
  const signature = hmac.update(md5Hex).digest('base64');
  return signature;
}
const requestBody = 'your_request_body';
const secret = 'your_secret_key';
const signature = getSignature(requestBody, secret);
console.log(signature); 

Key Integration Notes

• Callback is a core part of reward redemption, not a generic webhook

• It is triggered only after Enable3 validation

• The administrator must produce the final user-facing reward result

• The request identifier must be treated as an idempotency key

• Duplicate requests must not create duplicate rewards

• Enable3 manages lifecycle, balance, retries, and storage

• The admin manages fulfillment, business logic, and external integrations

• Retry and timeout behavior must be expected and handled

• The final reward shown to the user comes from the admin response