API Reference
Base URL: https://joy.avada.io/app/api/v1
Webhook management
List Webhooks
Get a list of all registered webhooks for your shop.
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Webhook API","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Webhook management operations"}],"servers":[{"url":"https://joy.avada.io/app/api/v1"}],"paths":{"/webhooks":{"get":{"tags":["Webhooks"],"summary":"List Webhooks","description":"Get a list of all registered webhooks for your shop.","parameters":[{"name":"X-Joy-Loyalty-App-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Your Joy app key from settings"},{"name":"X-Joy-Loyalty-Secret-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Your Joy secret key from settings"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"timestamp":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Webhook":{"type":"object","properties":{"id":{"type":"string","description":"Unique webhook identifier"},"topic":{"type":"string","description":"Webhook topic"},"url":{"type":"string","format":"uri","description":"Webhook endpoint URL"},"isEnabled":{"type":"boolean","description":"Whether the webhook is enabled"},"createdAt":{"type":"string","format":"date-time","description":"Webhook creation timestamp"}}},"Error":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}Get Webhook by ID
Retrieve details of a specific webhook.
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Webhook API","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Webhook management operations"}],"servers":[{"url":"https://joy.avada.io/app/api/v1"}],"paths":{"/webhooks/{id}":{"get":{"tags":["Webhooks"],"summary":"Get Webhook by ID","description":"Retrieve details of a specific webhook.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID"},{"name":"X-Joy-Loyalty-App-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Your Joy app key from settings"},{"name":"X-Joy-Loyalty-Secret-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Your Joy secret key from settings"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"$ref":"#/components/schemas/Webhook"},"timestamp":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Webhook":{"type":"object","properties":{"id":{"type":"string","description":"Unique webhook identifier"},"topic":{"type":"string","description":"Webhook topic"},"url":{"type":"string","format":"uri","description":"Webhook endpoint URL"},"isEnabled":{"type":"boolean","description":"Whether the webhook is enabled"},"createdAt":{"type":"string","format":"date-time","description":"Webhook creation timestamp"}}},"Error":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}Create Webhook
Register a new webhook endpoint for a specific topic.
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Webhook API","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Webhook management operations"}],"servers":[{"url":"https://joy.avada.io/app/api/v1"}],"paths":{"/webhooks":{"post":{"tags":["Webhooks"],"summary":"Create Webhook","description":"Register a new webhook endpoint for a specific topic.","parameters":[{"name":"X-Joy-Loyalty-App-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Your Joy app key from settings"},{"name":"X-Joy-Loyalty-Secret-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Your Joy secret key from settings"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["topic","url"],"properties":{"topic":{"type":"string","description":"One of the supported webhook topics","enum":["points/earned","points/redeemed","points/expired","customer/status_changed","reward/coupon_used","tier/upgraded","tier/downgraded","referral/link_created","referral/reward_earned","birthday/reward_earned","milestone/achieved"]},"url":{"type":"string","format":"uri","description":"HTTPS URL endpoint to receive webhook notifications"}}}}}},"responses":{"200":{"description":"Webhook created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"$ref":"#/components/schemas/Webhook"},"timestamp":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Webhook":{"type":"object","properties":{"id":{"type":"string","description":"Unique webhook identifier"},"topic":{"type":"string","description":"Webhook topic"},"url":{"type":"string","format":"uri","description":"Webhook endpoint URL"},"isEnabled":{"type":"boolean","description":"Whether the webhook is enabled"},"createdAt":{"type":"string","format":"date-time","description":"Webhook creation timestamp"}}},"Error":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}Update Webhook
Update an existing webhook (enable/disable or change URL).
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Webhook API","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Webhook management operations"}],"servers":[{"url":"https://joy.avada.io/app/api/v1"}],"paths":{"/webhooks/{id}":{"put":{"tags":["Webhooks"],"summary":"Update Webhook","description":"Update an existing webhook (enable/disable or change URL).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID"},{"name":"X-Joy-Loyalty-App-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Your Joy app key from settings"},{"name":"X-Joy-Loyalty-Secret-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Your Joy secret key from settings"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"New webhook URL"},"isEnabled":{"type":"boolean","description":"Enable or disable the webhook"}}}}}},"responses":{"200":{"description":"Webhook updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"$ref":"#/components/schemas/Webhook"},"timestamp":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Webhook":{"type":"object","properties":{"id":{"type":"string","description":"Unique webhook identifier"},"topic":{"type":"string","description":"Webhook topic"},"url":{"type":"string","format":"uri","description":"Webhook endpoint URL"},"isEnabled":{"type":"boolean","description":"Whether the webhook is enabled"},"createdAt":{"type":"string","format":"date-time","description":"Webhook creation timestamp"}}},"Error":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}Delete Webhook
Remove a webhook registration.
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Webhook API","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Webhook management operations"}],"servers":[{"url":"https://joy.avada.io/app/api/v1"}],"paths":{"/webhooks/{id}":{"delete":{"tags":["Webhooks"],"summary":"Delete Webhook","description":"Remove a webhook registration.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook ID"},{"name":"X-Joy-Loyalty-App-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Your Joy app key from settings"},{"name":"X-Joy-Loyalty-Secret-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Your Joy secret key from settings"}],"responses":{"200":{"description":"Webhook deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}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 |