# 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           |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devdocs.joy.so/webhook-api/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.