> Tychron Atlas API & Provisioning Reference — chapter 30 of 35 as Markdown. Web version: https://docs.tychron.com/api-reference/event-subscriptions/
> Source: https://docs.tychron.com/api-reference/ · Updated 2026-08-12 · Generated from the Atlas OpenAPI spec (https://api.atlas.tychron.online/api/v1/openapi is the live contract; this file is a dated snapshot of it).
> Source revision: atlas_api_reference_2026-08-12.md · sha256 482ebd3b014af053 · sanitize gate v1 clean · reconciled with OpenAPI 2026.8.25-p01 (spec sha256 cc049ef38c71cd6e) on 2026-09-05 · content last modified 2026-09-09 · newer definition under review since 2026-09-09 (not yet reconciled)
> Scope: the Atlas platform API only. The SMS, MMS, CNAM, LRN and MCL services are separate APIs with their own specifications: https://docs.tychron.com/openapi/
> Machine index: https://docs.tychron.com/llms.txt

# Event Subscriptions

## Schema

Event Subscription

__Type__ Object

| Name                  | Type                                                 | Description                         |
| --------------------- | ---------------------------------------------------- | ----------------------------------- |
| `auth_identity`       | String                                               | [Desc. `auth_identity`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-413)  |
| `auth_method`         | Enum(`NONE`, `BASIC`, `BEARER`):String               | [Desc. `auth_method`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-414)    |
| `auth_name`           | String                                               | [Desc. `auth_name`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-415)      |
| `auth_secret`         | String                                               | [Desc. `auth_secret`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-416)    |
| `custom_headers`      | Array:[SubObject](https://docs.tychron.com/api-reference/event-subscriptions/#type-417)                         | [Desc. `custom_headers`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-418) |
| `custom_query_params` | Array:[SubObject](https://docs.tychron.com/api-reference/event-subscriptions/#type-419)                         |                                     |
| `data`                | String                                               | [Desc. `data`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-420)           |
| `enabled`             | Boolean                                              | [Desc. `enabled`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-421)        |
| `expired_at`          | String(format:date-time)                             | An ISO8601 formatted timestamp      |
| `id`                  | String(format:uuid)                                  | [Desc. `id`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-422)             |
| `inserted_at`         | String(format:date-time)                             | An ISO8601 formatted timestamp      |
| `name`                | String(..255)                                        | [Desc. `name`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-423)           |
| `notes`               | String(..65535)                                      | [Desc. `notes`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-424)          |
| `protocol`            | Enum(`NONE`, `HTTP`, `SMTP`, `SFTP`, `EMAIL`):String | [Desc. `protocol`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-425)       |
| `recipient`           | String                                               | [Desc. `recipient`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-426)      |
| `started_at`          | String(format:date-time)                             | An ISO8601 formatted timestamp      |
| `topics`              | Array:[Enum](https://docs.tychron.com/api-reference/event-subscriptions/#enum-427):String                       | [Desc. `topics`](https://docs.tychron.com/api-reference/event-subscriptions/#desc-428)         |
| `updated_at`          | String(format:date-time)                             | An ISO8601 formatted timestamp      |

#### Desc. `auth_identity` {#desc-413}

Acts as the `username` for an auth pair.

#### Desc. `auth_method` {#desc-414}

Depending on the protocol this will affect the authorization or authentication that will be performed.

This applies to HTTP, SMTP and SFTP.

* `NONE` - no auth is required the event will be sent as is
* `BASIC` - The `auth_identity` and `auth_secret` will form the auth pair
* `BEARER` - Only the `auth_secret` will be used where applicable, for protocols that require both a username and password, the username will have a placeholder value.

#### Desc. `auth_name` {#desc-415}

Currently unused, but kept for future use.

#### Desc. `auth_secret` {#desc-416}

Acts as the `password` for an auth pair or just the general secret.

#### SubObject {#type-417}

Sub-Schema

A single header entry, while multiple items can be provided with the same key, the behaviour
may not be consistent between destination servers.

When in doubt, only use unique keys.


__Type__ Object

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `key`   | String |             |
| `value` | String |             |





#### Desc. `custom_headers` {#desc-418}

A list of additional headers that should be provided during the HTTP request.

#### SubObject {#type-419}

Sub-Schema

A single query parameter pair.


__Type__ Object

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `key`   | String |             |
| `value` | String |             |





#### Desc. `data` {#desc-420}

Depending on the protocol specified this may be an http endpoint (HTTP), a hostname (SMTP or SFTP) or an email address (EMAIL).

Protocol:
* `NONE` - nothing, this field is unused
* `HTTP` - the http server endpoint (e.g. "http://events.example.com:7654/events/v1/ordering")
* `SFTP` - the sftp server address (e.g. "sftp://sftp.example.com:2231/path/to/upload")
* `SMTP` - the relay server address (e.g. "smtp://smtp.example.com:2554")
* `EMAIL` - the recipient email address (e.g. "john.doe@example.com")

A keen eye may notice there was no mention of the recipient address for SMTP, that is covered in `recipient`.

#### Desc. `enabled` {#desc-421}

Is the subscription enabled to handle events?

Subscriptions can be toggled on or off as needed.

#### Desc. `id` {#desc-422}

A Universally unique identifier, which identifies the resource

#### Desc. `name` {#desc-423}

The friendly given name for this subscription

#### Desc. `notes` {#desc-424}

Any additional information about this subscription that otherwise could not fit into the name.

This can be useful to another user or agent that is reviewing the subscription.

#### Desc. `protocol` {#desc-425}

When the subscription receives an event for handling, it wil be processed and sent using the specified protocol.

Available:
* `NONE` - effectively a no-op.
* `HTTP` - sends the event over HTTP to a specified endpoint `data`.
* `SFTP` - uploads the event to a specified SFTP server

Planned (currently unavailable, but may become available later):
* `SMTP` - sends the event over SMTP (not email compatible)
* `EMAIL` - emails the event to specified address in `data`

#### Desc. `recipient` {#desc-426}

Only applicable when the `protocol` is SMTP, this will be the recipient address (e.g. "events@example.com")

#### Enum Values topics {#enum-427}

Allowed values

* `NONE`
* `DID`
* `CSP_BRAND`
* `CSP_CAMPAIGN`
* `ORDER`
* `REQUEST`
* `OSR`

#### Desc. `topics` {#desc-428}

An event subscription must be list topics it wishes to receive events for.



__Example__

```json
{
  "auth_identity": "my-username",
  "auth_method": "NONE",
  "auth_name": "something",
  "auth_secret": "my-secret-password",
  "custom_headers": [
    {
      "key": "x-my-header",
      "value": "My Header Value"
    }
  ],
  "custom_query_params": [
    {
      "key": "my_param",
      "value": "ParamValue"
    }
  ],
  "data": "",
  "enabled": true,
  "expired_at": "2021-08-13T04:08:44.762841Z",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "CSP Events",
  "notes": "string",
  "protocol": "NONE",
  "recipient": "events@example.com",
  "started_at": "2021-08-13T04:08:44.762841Z",
  "topics": [
    "NONE"
  ],
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```


## Summary

Event Subscriptions are records used to define event related webhook configuration.

These events are typically sent from the ordering system in response to an order or request being completed, a did being updated, or an overwrite request pending action.

## API

### Create Event Subscription

```http
POST /api/v1/event_subscriptions HTTP/1.1
```

Create a new Event Subscription.


#### Request application/json

```http
POST /api/v1/event_subscriptions HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 590
```

```json
{
  "data": {
    "auth_identity": "my-username",
    "auth_method": "NONE",
    "auth_name": "something",
    "auth_secret": "my-secret-password",
    "custom_headers": [
      {
        "key": "x-my-header",
        "value": "My Header Value"
      }
    ],
    "custom_query_params": [
      {
        "key": "my_param",
        "value": "ParamValue"
      }
    ],
    "data": "",
    "enabled": true,
    "name": "CSP Events",
    "notes": "string",
    "protocol": "NONE",
    "recipient": "events@example.com",
    "topics": [
      "NONE"
    ]
  },
  "type": "event_subscription"
}
```

#### Response 201

##### application/json

```http
HTTP/1.1 201
Content-Type: application/json
Content-Length: 837
```

```json
{
  "data": {
    "auth_identity": "my-username",
    "auth_method": "NONE",
    "auth_name": "something",
    "auth_secret": "my-secret-password",
    "custom_headers": [
      {
        "key": "x-my-header",
        "value": "My Header Value"
      }
    ],
    "custom_query_params": [
      {
        "key": "my_param",
        "value": "ParamValue"
      }
    ],
    "data": "",
    "enabled": true,
    "expired_at": "2021-08-13T04:08:44.762841Z",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "CSP Events",
    "notes": "string",
    "protocol": "NONE",
    "recipient": "events@example.com",
    "started_at": "2021-08-13T04:08:44.762841Z",
    "topics": [
      "NONE"
    ],
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "event_subscription"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Update Event Subscription

```http
PATCH /api/v1/event_subscriptions/{id} HTTP/1.1
```

Update an existing Event Subscription


__Path Parameters__

| Name | Type                 | Description           |
| ---- | -------------------- | --------------------- |
| id   | String(format:uuid)! | Event Subscription ID |

#### Request application/json

```http
PATCH /api/v1/event_subscriptions/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 590
```

```json
{
  "data": {
    "auth_identity": "my-username",
    "auth_method": "NONE",
    "auth_name": "something",
    "auth_secret": "my-secret-password",
    "custom_headers": [
      {
        "key": "x-my-header",
        "value": "My Header Value"
      }
    ],
    "custom_query_params": [
      {
        "key": "my_param",
        "value": "ParamValue"
      }
    ],
    "data": "",
    "enabled": true,
    "name": "CSP Events",
    "notes": "string",
    "protocol": "NONE",
    "recipient": "events@example.com",
    "topics": [
      "NONE"
    ]
  },
  "type": "event_subscription"
}
```

#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 837
```

```json
{
  "data": {
    "auth_identity": "my-username",
    "auth_method": "NONE",
    "auth_name": "something",
    "auth_secret": "my-secret-password",
    "custom_headers": [
      {
        "key": "x-my-header",
        "value": "My Header Value"
      }
    ],
    "custom_query_params": [
      {
        "key": "my_param",
        "value": "ParamValue"
      }
    ],
    "data": "",
    "enabled": true,
    "expired_at": "2021-08-13T04:08:44.762841Z",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "CSP Events",
    "notes": "string",
    "protocol": "NONE",
    "recipient": "events@example.com",
    "started_at": "2021-08-13T04:08:44.762841Z",
    "topics": [
      "NONE"
    ],
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "event_subscription"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Delete Event Subscription

```http
DELETE /api/v1/event_subscriptions/{id} HTTP/1.1
```

Delete an existing Event Subscription by ID.


__Path Parameters__

| Name | Type                 | Description           |
| ---- | -------------------- | --------------------- |
| id   | String(format:uuid)! | Event Subscription ID |

#### Request

```http
DELETE /api/v1/event_subscriptions/{id} HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 837
```

```json
{
  "data": {
    "auth_identity": "my-username",
    "auth_method": "NONE",
    "auth_name": "something",
    "auth_secret": "my-secret-password",
    "custom_headers": [
      {
        "key": "x-my-header",
        "value": "My Header Value"
      }
    ],
    "custom_query_params": [
      {
        "key": "my_param",
        "value": "ParamValue"
      }
    ],
    "data": "",
    "enabled": true,
    "expired_at": "2021-08-13T04:08:44.762841Z",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "CSP Events",
    "notes": "string",
    "protocol": "NONE",
    "recipient": "events@example.com",
    "started_at": "2021-08-13T04:08:44.762841Z",
    "topics": [
      "NONE"
    ],
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "event_subscription"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314
```

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```
#### Response 422

##### application/json

```http
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### List Event Subscriptions

```http
GET /api/v1/event_subscriptions HTTP/1.1
```

Retrieve all event subscriptions for account


__Query Parameters__

| Name   | Type    | Description                     |
| ------ | ------- | ------------------------------- |
| first  | Integer | [Query Desc. first](https://docs.tychron.com/api-reference/event-subscriptions/#desc-429)  |
| last   | Integer | [Query Desc. last](https://docs.tychron.com/api-reference/event-subscriptions/#desc-430)   |
| after  | String  | [Query Desc. after](https://docs.tychron.com/api-reference/event-subscriptions/#desc-431)  |
| before | String  | [Query Desc. before](https://docs.tychron.com/api-reference/event-subscriptions/#desc-432) |

#### Query Desc. first {#desc-429}

The number of items to return starting from the 'after' cursor

#### Query Desc. last {#desc-430}

The number of items to return behind the 'before' cursor

#### Query Desc. after {#desc-431}

The cursor representing the starting point of a 'first' based paging

#### Query Desc. before {#desc-432}

The cursor representing the starting point of a 'last' based paging

#### Request

```http
GET /api/v1/event_subscriptions HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 1138
```

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "auth_identity": "my-username",
        "auth_method": "NONE",
        "auth_name": "something",
        "auth_secret": "my-secret-password",
        "custom_headers": [
          {
            "key": "x-my-header",
            "value": "My Header Value"
          }
        ],
        "custom_query_params": [
          {
            "key": "my_param",
            "value": "ParamValue"
          }
        ],
        "data": "",
        "enabled": true,
        "expired_at": "2021-08-13T04:08:44.762841Z",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "CSP Events",
        "notes": "string",
        "protocol": "NONE",
        "recipient": "events@example.com",
        "started_at": "2021-08-13T04:08:44.762841Z",
        "topics": [
          "NONE"
        ],
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "event_subscription"
    }
  ]
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```


### Get Event Subscription

```http
GET /api/v1/event_subscriptions/{id} HTTP/1.1
```

Lookup an Event Subscription by its ID


__Path Parameters__

| Name | Type                 | Description           |
| ---- | -------------------- | --------------------- |
| id   | String(format:uuid)! | Event Subscription ID |

#### Request

```http
GET /api/v1/event_subscriptions/{id} HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 837
```

```json
{
  "data": {
    "auth_identity": "my-username",
    "auth_method": "NONE",
    "auth_name": "something",
    "auth_secret": "my-secret-password",
    "custom_headers": [
      {
        "key": "x-my-header",
        "value": "My Header Value"
      }
    ],
    "custom_query_params": [
      {
        "key": "my_param",
        "value": "ParamValue"
      }
    ],
    "data": "",
    "enabled": true,
    "expired_at": "2021-08-13T04:08:44.762841Z",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "CSP Events",
    "notes": "string",
    "protocol": "NONE",
    "recipient": "events@example.com",
    "started_at": "2021-08-13T04:08:44.762841Z",
    "topics": [
      "NONE"
    ],
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "event_subscription"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314
```

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```

---

Previous chapter: https://docs.tychron.com/api-reference/shared-resource-groups.md  
Next chapter: https://docs.tychron.com/api-reference/events.md  
Complete reference in one file: https://docs.tychron.com/llms-full.txt