List event subscriptions

Browse API reference

GET/event-subscriptionslistEventSubscriptions

Use this method to return a paginated list of event subscriptions that are linked to your ISV account.

Note: If you want to view the details of a specific event subscription and you have its id, use our Retrieve Event Subscription method.

Use query parameters to filter the list of results that we return, for example, to search for subscriptions with a specific status or an event type.

Our gateway returns the following information about each subscription in the list:

Event types that you have subscribed to.
Whether you have enabled notifications for the subscription.
How we contact you when an event occurs, including the endpoint that send notifications to.
If there are any issues when we try to send you a notification, for example, if we can't contact your endpoint.

For each event subscription, we also return its id, which you can use to perform follow-on actions.

Parameters

Name	In	Type	Description
`status`	query	`string`	Filter event subscriptions by subscription status.
`event`	query	`string`	Filter event subscriptions by an event type. For a list of event types, go to Events List.

Responses

Successful request. Returns a list of event subscriptions.

200 OK · application/json

{
  "count": 2,
  "data": [
    {
      "enabled": true,
      "eventTypes": [
        "processingAccount.status.changed"
      ],
      "id": 2565435189324,
      "metadata": {
        "yourCustomField": "abc123"
      },
      "notifications": [
        {
          "secret": "**********oP3456",
          "supportEmailAddress": "jane.doe@example.com",
          "type": "webhook",
          "uri": "https://my-server/notification/endpoint"
        }
      ],
      "status": "registered"
    },
    {
      "enabled": true,
      "eventTypes": [
        "processingAccount.riskStatus.changed"
      ],
      "id": 2565435189325,
      "metadata": {
        "yourCustomField": "abc123"
      },
      "notifications": [
        {
          "secret": "**********oP3456",
          "supportEmailAddress": "jane.doe@example.com",
          "type": "webhook",
          "uri": "https://my-server/notification/endpoint"
        }
      ],
      "status": "registered"
    }
  ],
  "hasMore": false,
  "limit": 10,
  "links": [
    {
      "href": "https://api.payroc.com/v1/event-subscriptions?after=10&limit=10",
      "method": "get",
      "rel": "next"
    }
  ]
}

Response schema · 15 of 19 fields

countinteger
Number of results we returned on this page. Note: This might not be the total number of results that match your query.
hasMoreboolean
Indicates whether there is another page of results available.
limitinteger
Maximum number of results that we return for each page.
linksobject[]
Reference links to navigate to the previous page of results or to the next page of results.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
dataobject[]
Array of eventSubscription objects.
- enabledbooleanrequired
  Indicates if we should notify you when the event occurs. The value is one of the following: true We notify you when the event occurs. false We don't notify you when the event occurs.
- eventTypesstring[]required
  Array of events that you want to subscribe to. For a list of events, go to Events List.
- idintegerint64
  Unique identifier that we assigned to the event subscription.
- metadataobject
  Object that you can send to include custom data in the request. For more information about how to use metadata, go to Metadata.
- notificationsobject[]required
  Array of polymorphic notification objects that contain information about how we contact you when an event occurs.
  - option 1object
    +4 more fields at deeper levels — see the full spec
- statusstring
  Status of the subscription. We return one of the following values: registered You have set up the subscription, and we will notify you when an event occurs. suspended We have deactivated the event subscription, and we won't notify you when an event occurs. failed We couldn't contact your URI endpoint. We email the supportEmailAddress.registeredsuspendedfailed

Invalid request

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid date",
      "message": "Expected time, got '' for start_time",
      "parameter": "start_time"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "https://docs.payroc.com/api/errors#bad-request"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

create-event-subscription