SubscriptionsController API Documentation

Subscriptions API Documentation

The Subscriptions API allows partners to manage webhook subscriptions for receiving notifications from the EZ Rewards platform. All endpoints require JWT Bearer authentication.

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:

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

Request Parameters:

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

Response:

{
  "statusCode": 202,
  "subscriptions": [
    {
      "callbarkUrl": "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": [
    {
      "callbarkUrl": "https://example.com/webhook1",
      "id": 123
    },
    {
      "callbarkUrl": "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 CallbarkUrl { 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 CallbarkUrl { 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 "CallbarkUrl" (instead of "CallbackUrl") 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