# API Reference

{% hint style="success" %}
**Base URL:** `https://joy.avada.io/app/api/v1`
{% endhint %}

## Webhook management

## List Webhooks

> Get a list of all registered webhooks for your shop.

```json
{"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.

```json
{"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.

```json
{"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).

```json
{"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.

```json
{"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           |