> ## Documentation Index
> Fetch the complete documentation index at: https://docs.exowizz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions

> Create and manage webhook subscriptions through the API or the dashboard.

A webhook subscription tells Exo where to send notifications and which events to listen for. Each subscription targets one resource and one or more trigger events.

## Creating a subscription via the API

Send a `POST` request to the webhooks endpoint:

```bash theme={null}
curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://example.com/webhook-receiver",
       "resource": "order",
       "events": ["on_create", "on_update"]
     }' \
     http://your-app.test/exo-api/webhooks
```

The response includes the subscription details and the webhook secret:

```json theme={null}
{
  "id": 1,
  "user_id": 1,
  "url": "https://example.com/webhook-receiver",
  "resource": "order",
  "events": ["on_create", "on_update"],
  "secret": "a1b2c3d4e5f6...",
  "is_active": true,
  "created_at": "2026-03-28T14:30:00.000000Z",
  "updated_at": "2026-03-28T14:30:00.000000Z"
}
```

<Warning>
  The `secret` is only returned in full when you first create the subscription. Store it securely — you'll need it to verify webhook signatures. After creation, only a masked version is shown.
</Warning>

## Subscription fields

| Field      | Required | Description                                                                    |
| ---------- | -------- | ------------------------------------------------------------------------------ |
| `url`      | Yes      | The URL that receives webhook POST requests (max 2048 characters)              |
| `resource` | Yes      | The resource name (e.g. `order`, `contact`) — must match a registered resource |
| `events`   | Yes      | Array of trigger events to subscribe to: `on_create`, `on_update`, `on_delete` |

The events array must only contain triggers that the resource supports. For example, if a resource only defines `['on_create']` in its `triggers()` method, you cannot subscribe to `on_update`.

Exo's built-in model observer emits `on_create`, `on_update`, and `on_delete`.

## Listing subscriptions

List all your webhook subscriptions:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://your-app.test/exo-api/webhooks
```

## Updating a subscription

Update the URL or events of an existing subscription:

```bash theme={null}
curl -X PUT \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"events": ["on_create", "on_update", "on_delete"]}' \
     http://your-app.test/exo-api/webhooks/1
```

<Note>
  You cannot change the `resource` of an existing subscription. Delete it and create a new one instead.
</Note>

## Deleting a subscription

```bash theme={null}
curl -X DELETE \
     -H "Authorization: Bearer YOUR_TOKEN" \
     http://your-app.test/exo-api/webhooks/1
```

## Activating and deactivating

Subscriptions have an `is_active` flag. When deactivated, Exo skips the subscription during webhook delivery without deleting it. You can toggle this through the Exo dashboard.

## Using the dashboard

Exo includes a web dashboard where you can manage subscriptions without writing API calls. Access it at `/exo/dashboard` (or whatever prefix you've configured).

From the dashboard you can:

* View all your webhook subscriptions
* Toggle subscriptions on and off
* Update webhook URLs and events
* Delete subscriptions
* See your API tokens
* Browse available resources and their triggers

<Note>
  The dashboard requires a separate login at `/exo/login`. This is independent from your main application login.
</Note>