# Subscriptions

## Overview

Subscriptions allow external systems to **receive automatic notifications** when certain resources in the API change.
By registering a subscription, your system can stay synchronized without the need for polling.

Each subscription represents a **webhook configuration** tied to one or more event types (e.g. `created`, `updated`, `deleted`) for a given resource.

## Endpoints

### List Subscriptions

`GET /api/v1/resources/subscriptions`

Returns all active subscriptions for the current authenticated user or consumer.

**Response Example**


```json
{
  "count": 1,
  "subscriptions": [
    {
      "id": "f2b8e9d3-31c5-4a77-b814-f447bbab9fd2",
      "resource_type": "subscription",
      "webhook_url": "https://example.com/webhooks/receive",
      "event_type": ["created", "updated"],
      "status": "active",
      "start_date": "2024-01-01T00:00:00Z",
      "end_date": null
    }
  ]
}
```

### Create Subscription

`POST /api/v1/resources/subscriptions`

Registers a new webhook endpoint for receiving events.

**Request Body**


```json
{
  "resource_type": "subscription",
  "webhook_url": "https://example.com/webhooks/receive",
  "event_type": ["created", "updated"]
}
```

| Field | Type | Description |
|  --- | --- | --- |
| `resource_type` | string | Must be `"subscription"`. |
| `webhook_url` | string | The HTTPS endpoint that will receive POST requests when an event occurs. |
| `event_type` | array | List of events to subscribe to (`created`, `updated`, `deleted`). |
| `start_date` | string *(optional)* | When the subscription becomes active. |
| `end_date` | string *(optional)* | When the subscription expires. |


**Response (201)**


```json
{
  "id": "f2b8e9d3-31c5-4a77-b814-f447bbab9fd2",
  "resource_type": "subscription",
  "webhook_url": "https://example.com/webhooks/receive",
  "event_type": ["created", "updated"],
  "status": "active",
  "signing_secret": "8d4e4a7f24c...c9820b"
}
```

### Get Subscription

`GET /api/v1/resources/subscriptions/{subscription}`

Retrieves a single subscription by its unique ID (UUID).

### Test Subscription

`POST /api/v1/resources/subscriptions/{subscription}/test`

Triggers a test webhook call to the configured `webhook_url`.
The response will be `202 Accepted` if the test is queued successfully.

### Delete Subscription

`DELETE /api/v1/resources/subscriptions/{subscription}`

Cancels an existing subscription and stops event delivery.

## Webhook Event Delivery

When an event occurs (e.g. a product is created or updated), the system will send an **HTTP POST** request to your `webhook_url`.

**Example webhook payload**


```json
{
  "event_type": "updated",
  "resource": "product",
  "resource_id": "12345",
  "timestamp": "2025-10-21T12:00:00Z",
  "data": {
    "id": "12345",
    "name": "Updated Product Name"
  },
  "signature": "sha256=ab0b71c8..."
}
```

Each payload includes a `signature` generated using the `signing_secret` issued at subscription creation.
Use this signature to verify authenticity before processing the data.

## Security & Verification

- All webhook requests are **signed** using HMAC-SHA256 and the `signing_secret`.
- Webhook URLs **must use HTTPS**.
- Retry behavior may be implemented by the client; failed deliveries should be logged and retried as needed.


## Typical Flow

1. **Create** a subscription with your webhook URL.
2. **Verify** incoming webhook requests using the provided signing secret.
3. **Receive** notifications automatically whenever a subscribed event occurs.
4. **Test** the webhook endpoint with `/test`.
5. **Delete** the subscription when no longer needed.


## Best Practices

- Respond with `2xx` to confirm successful webhook receipt.
- Use **idempotency** when processing duplicate events.
- Store the `subscription.id` to manage or revoke later.
- Rotate `signing_secret` periodically for security.