API Reference

Base URL: https://joy.avada.io/app/api/v1

Webhook management

List Webhooks

get

Get a list of all registered webhooks for your shop.

Header parameters

X-Joy-Loyalty-App-KeystringRequired

Your Joy app key from settings

X-Joy-Loyalty-Secret-KeystringRequired

Your Joy secret key from settings

Responses

200

Success

application/json

401

Unauthorized

application/json

get

/webhooks

HTTPcURLJavaScriptPython

GET /app/api/v1/webhooks HTTP/1.1
Host: joy.avada.io
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
Accept: */*

{
  "success": true,
  "webhooks": [
    {
      "id": "webhook_abc123",
      "topic": "points/earned",
      "url": "https://your-server.com/webhook/points",
      "isEnabled": true,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Get Webhook by ID

get

Retrieve details of a specific webhook.

Path parameters

idstringRequired

Webhook ID

Example: webhook_abc123

Header parameters

X-Joy-Loyalty-App-KeystringRequired

Your Joy app key from settings

X-Joy-Loyalty-Secret-KeystringRequired

Your Joy secret key from settings

Responses

200

Success

application/json

404

Webhook not found

application/json

get

/webhooks/{id}

HTTPcURLJavaScriptPython

GET /app/api/v1/webhooks/{id} HTTP/1.1
Host: joy.avada.io
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
Accept: */*

{
  "success": true,
  "webhook": {
    "id": "webhook_abc123",
    "topic": "points/earned",
    "url": "https://your-server.com/webhook/points",
    "isEnabled": true,
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2026-02-10T08:37:30.466Z"
}

Create Webhook

post

Register a new webhook endpoint for a specific topic.

Header parameters

X-Joy-Loyalty-App-KeystringRequired

Your Joy app key from settings

X-Joy-Loyalty-Secret-KeystringRequired

Your Joy secret key from settings

Body

application/json

topicstring · enumRequired

One of the supported webhook topics

Example: points/earnedPossible values:

urlstring · uriRequired

HTTPS URL endpoint to receive webhook notifications

Example: https://your-server.com/webhook/points

Responses

200

Webhook created successfully

application/json

400

Bad Request

application/json

post

/webhooks

HTTPcURLJavaScriptPython

POST /app/api/v1/webhooks HTTP/1.1
Host: joy.avada.io
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 72

{
  "topic": "points/earned",
  "url": "https://your-server.com/webhook/points"
}

{
  "success": true,
  "webhook": {
    "id": "webhook_abc123",
    "topic": "points/earned",
    "url": "https://your-server.com/webhook/points",
    "isEnabled": true,
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2026-02-10T08:37:30.466Z"
}

Update Webhook

put

Update an existing webhook (enable/disable or change URL).

Path parameters

idstringRequired

Webhook ID

Example: webhook_abc123

Header parameters

X-Joy-Loyalty-App-KeystringRequired

Your Joy app key from settings

X-Joy-Loyalty-Secret-KeystringRequired

Your Joy secret key from settings

Body

application/json

urlstring · uriOptional

New webhook URL

Example: https://new-server.com/webhook/points

isEnabledbooleanOptional

Enable or disable the webhook

Example: false

Responses

200

Webhook updated successfully

application/json

404

Webhook not found

application/json

put

/webhooks/{id}

HTTPcURLJavaScriptPython

PUT /app/api/v1/webhooks/{id} HTTP/1.1
Host: joy.avada.io
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "url": "https://new-server.com/webhook/points",
  "isEnabled": false
}

{
  "success": true,
  "webhook": {
    "id": "webhook_abc123",
    "topic": "points/earned",
    "url": "https://your-server.com/webhook/points",
    "isEnabled": true,
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "timestamp": "2026-02-10T08:37:30.466Z"
}

Delete Webhook

delete

Remove a webhook registration.

Path parameters

idstringRequired

Webhook ID

Example: webhook_abc123

Header parameters

X-Joy-Loyalty-App-KeystringRequired

Your Joy app key from settings

X-Joy-Loyalty-Secret-KeystringRequired

Your Joy secret key from settings

Responses

200

Webhook deleted successfully

application/json

404

Webhook not found

application/json

delete

/webhooks/{id}

HTTPcURLJavaScriptPython

DELETE /app/api/v1/webhooks/{id} HTTP/1.1
Host: joy.avada.io
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
Accept: */*

{
  "success": true,
  "timestamp": "2026-02-10T08:37:30.466Z"
}

Error handling

HTTP status codes

Code	Description	Common Scenarios
200	Success	Request completed successfully
400	Bad Request	Invalid parameters or request data
401	Unauthorized	Missing or invalid authentication
404	Not Found	Webhook does not exist
500	Internal Server Error	Unexpected server error

Common error codes

Error Message	Cause	Resolution
Invalid post data	Malformed request body or missing required fields	Check request format and required parameters
Webhook is already existing with the same topic and url	Duplicate webhook registration	Use a different URL or topic combination
Unauthorized	Invalid or missing authentication headers	Verify your app key and secret key