We use cookies to give you the best possible experience while you browse through our site. By continuing to use our website you implicitly agree to the usage of cookies on this site.

Read More
← Atlas API & Provisioning Reference

Event Subscriptions

Schema

Event Subscription

Type Object

Name Type Description
auth_identity String Desc. auth_identity
auth_method Enum(NONE, BASIC, BEARER):String Desc. auth_method
auth_name String Desc. auth_name
auth_secret String Desc. auth_secret
custom_headers Array:SubObject Desc. custom_headers
custom_query_params Array:SubObject
data String Desc. data
enabled Boolean Desc. enabled
expired_at String(format:date-time) An ISO8601 formatted timestamp
id String(format:uuid) Desc. id
inserted_at String(format:date-time) An ISO8601 formatted timestamp
name String(..255) Desc. name
notes String(..65535) Desc. notes
protocol Enum(NONE, HTTP, SMTP, SFTP, EMAIL):String Desc. protocol
recipient String Desc. recipient
started_at String(format:date-time) An ISO8601 formatted timestamp
topics Array:Enum:String Desc. topics
updated_at String(format:date-time) An ISO8601 formatted timestamp

Desc. auth_identity

Acts as the username for an auth pair.

Desc. auth_method

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

Currently unused, but kept for future use.

Desc. auth_secret

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

SubObject

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

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

SubObject

Sub-Schema

A single query parameter pair.

Type Object

Name Type Description
key String
value String

Desc. data

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. "[email protected]")

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

Desc. enabled

Is the subscription enabled to handle events?

Subscriptions can be toggled on or off as needed.

Desc. id

A Universally unique identifier, which identifies the resource

Desc. name

The friendly given name for this subscription

Desc. notes

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

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

Only applicable when the protocol is SMTP, this will be the recipient address (e.g. "[email protected]")

Enum Values topics

Allowed values

  • NONE
  • DID
  • CSP_BRAND
  • CSP_CAMPAIGN
  • ORDER
  • REQUEST
  • OSR

Desc. topics

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

Example

{
  "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": "[email protected]",
  "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

POST /api/v1/event_subscriptions HTTP/1.1

Create a new Event Subscription.

Request application/json

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

{
  "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": "[email protected]",
    "topics": [
      "NONE"
    ]
  },
  "type": "event_subscription"
}

Response 201

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

{
  "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": "[email protected]",
    "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 241

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

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

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

{
  "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": "[email protected]",
    "topics": [
      "NONE"
    ]
  },
  "type": "event_subscription"
}

Response 200

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

{
  "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": "[email protected]",
    "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 241

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

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

DELETE /api/v1/event_subscriptions/{id} HTTP/1.1
Accept: application/json

Response 200

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

{
  "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": "[email protected]",
    "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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/1.1 422
Content-Type: application/json
Content-Length: 241

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

GET /api/v1/event_subscriptions HTTP/1.1

Retrieve all event subscriptions for account

Query Parameters

Name Type Description
first Integer Query Desc. first
last Integer Query Desc. last
after String Query Desc. after
before String Query Desc. before

Query Desc. first

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

Query Desc. last

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

Query Desc. after

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

Query Desc. before

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

Request

GET /api/v1/event_subscriptions HTTP/1.1
Accept: application/json

Response 200

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

{
  "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": "[email protected]",
        "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/1.1 403
Content-Type: application/json
Content-Length: 312

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

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

GET /api/v1/event_subscriptions/{id} HTTP/1.1
Accept: application/json

Response 200

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

{
  "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": "[email protected]",
    "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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"
    }
  ]
}

Updated 2026-08-12 · Generated from the Atlas OpenAPI spec.