SubscriptionsController API Documentation

Subscriptions API Documentation

The Subscriptions API allows partners to manage webhook subscriptions for receiving notifications from the EZ Rewards platform. Partners can register webhook endpoints that will receive notifications about point value updates and other important events. All endpoints require JWT Bearer authentication.

Table of Contents

• Authorization
• Endpoints
  • Create Subscription
  • Delete Subscription
  • Get Subscriptions
• Models
  • SubscriptionRequest
  • SubscriptionResponse
  • SubscriptionDetailsResponse
• Notes
• Webhook Notifications
  • Payload Structure
  • Payload Fields
  • Delivery Behavior

Authorization

All endpoints in this API require JWT Bearer authentication. The token must include a "PartnerId" claim that identifies the partner making the request.

Authorization: Bearer {jwt_token}

Endpoints

Create Subscription

Creates a new webhook subscription for the authenticated partner.

Endpoint: POST /api/Subscriptions

Authentication: JWT Bearer token required

Request Body:

{
  "callbackUrl": "https://example.com/webhook",
  "id": 0  // Optional, typically not needed for creation
}

Request Parameters:

Parameter	Type	Required	Description
callbackUrl	Uri	Yes	The URL that will receive webhook notifications
id	long	No	Identifier (not typically used for creation)

Response:

{
  "statusCode": 202,
  "subscriptions": [
    {
      "callbackUrl": "https://example.com/webhook",
      "id": 123
    }
  ]
}

Response Details:

Field	Type	Description
statusCode	HttpStatusCode	Status of the operation (202 Accepted for success)
subscriptions	Array	List containing the newly created subscription

Status Codes:

• 202 Accepted: Subscription created successfully
• 400 Bad Request: Invalid request or error during creation
• 404 Not Found: Partner not found

---

Delete Subscription

Deletes an existing webhook subscription.

Endpoint: DELETE /api/Subscriptions/{subscriptionId}

Authentication: JWT Bearer token required

URL Parameters:

Parameter	Type	Required	Description
subscriptionId	long	Yes	ID of the subscription to delete

Response:

{
  // Number of affected rows (typically 1 for success, -1 for not found)
}

Status Codes:

• 200 OK: Request processed (check return value to determine success)
  • Return value > 0: Subscription deleted successfully
  • Return value -1: Subscription not found

---

Get Subscriptions

Retrieves all webhook subscriptions for the authenticated partner.

Endpoint: GET /api/Subscriptions

Authentication: JWT Bearer token required

Response:

{
  "statusCode": 200,
  "subscriptions": [
    {
      "callbackUrl": "https://example.com/webhook1",
      "id": 123
    },
    {
      "callbackUrl": "https://example.com/webhook2",
      "id": 124
    }
  ]
}

Response Details:

Field	Type	Description
statusCode	HttpStatusCode	Status of the operation
subscriptions	Array	List of subscription details

Status Codes:

• 200 OK: Subscriptions retrieved successfully (may be an empty array)
• 404 Not Found: Partner not found
• 406 Not Acceptable: Error occurred during retrieval

Models

SubscriptionRequest

public class SubscriptionRequest
{
    [Required]
    public required Uri CallbackUrl { get; set; }

    public long Id { get; set; }
}

SubscriptionResponse

public class SubscriptionResponse
{
    public HttpStatusCode StatusCode { get; set; }

    public virtual List<SubscriptionDetailsResponse>? Subscriptions { get; set; }
}

SubscriptionDetailsResponse

public class SubscriptionDetailsResponse
{
    [Required]
    public required Uri CallbackUrl { get; set; }

    public long Id { get; set; }
}

Notes

• The API extracts the partner ID from the JWT token's claims
• There appears to be a typo in the property name "CallbackUrl" (instead of "CallbarkUrl") that is consistently used throughout the API
• All responses include an HTTP status code in the response body in addition to the standard HTTP status code in the response header

Webhook Notifications

Once subscribed, your webhook endpoint will receive POST requests with JSON payloads whenever point values are updated for users associated with your partner account. The system attempts to deliver webhooks immediately when point changes occur.

Payload Structure

{
  "user_id": 123,
  "pointValue": 100,
  "pointsLeft": 80,
  "pointsUsed": 20,
  "pointsUsedOnTransaction": 2000,
  "type": "new",
  "activityType": "Running",
  "reward" : "Brand - Reward",
  "rewardImage": "https://image.url.com"
}

Payload Fields

Field	Type	Description
user_id	long	ID of the user whose points were updated
pointValue	int	Total value of points in this transaction
pointsLeft	int	Remaining unused points
pointsUsed	int	Number of points already used
pointsUsedOnTransaction	int	Number of points used on the latest transaction eg 2000 spent unlocking x reward
type	string	Either "new" (if all points are unused) or "spent" (if some points have been used)
activityType	string	Name of the activity type associated with the points
reward	string	reward that the points were spent on if any
rewardImage	string	The main reward image

Delivery Behavior

• The system makes up to 4 retry attempts for failed webhook deliveries
• Webhook requests timeout after a reasonable period
• All webhook delivery attempts are logged in the system for audit purposes
• Successful delivery is determined by a 2xx HTTP response from your endpoint