---
title: "List event subscriptions"
method: GET
path: "/event-subscriptions"
tags: ["eventSubscriptions"]
---

# List event subscriptions

`GET /event-subscriptions`

Use this method to return a [paginated](https://docs.payroc.com/api/pagination) 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](https://docs.payroc.com/api/schema/notifications/event-subscriptions/retrieve) 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.

## Query parameters

- `status` 'registered' | 'suspended' | 'failed'
- `event` string

## Headers

- `Authorization` string, required

## Response `200`

Successful request. Returns a list of event subscriptions.

- PaginatedEventSubscriptions — Contains the pagination properties that you use to navigate through a list of results.
  - `limit` integer — Maximum number of results that we return for each page.
  - `count` integer — Number of results we returned on this page. **Note:** This might not be the total number of results that match your query.
  - `hasMore` boolean — Indicates whether there is another page of results available.
  - `links` Link[] — Reference links to navigate to the previous page of results or to the next page of results.
    - `rel` string, required — Indicates the relationship between the current resource and the target resource.
    - `method` string, required — HTTP method that you need to use with the target resource.
    - `href` string, required — URL of the target resource.
  - `data` EventSubscription[] — Array of eventSubscription objects.
    - `id` integer — Unique identifier that we assigned to the event subscription.
    - `enabled` boolean, required — 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.
    - `status` 'registered' | 'suspended' | 'failed' — 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.
    - `eventTypes` string[], required — Array of events that you want to subscribe to. For a list of events, go to [Events List](https://docs.payroc.com/knowledge/events/events-list).
    - `notifications` Notification[], required — Array of polymorphic notification objects that contain information about how we contact you when an event occurs.
      - `type` 'webhook', required — Discriminator value: webhook
      - `uri` string, required — Public endpoint that we send notifications to.
      - `secret` string, required — String that we send with a notification so that you can ensure it is a valid notification from our gateway. We include the value in the Payroc-Secret header parameter in the webhook call. **Note:** In the response, we truncate the secret to the last 16 characters and mask the first 10 characters.
      - `supportEmailAddress` string, required — Email address of the person or team that we contact if we can't deliver notifications.
    - `metadata` EventSubscriptionMetadata — Object that you can send to include custom data in the request. For more information about how to use metadata, go to [Metadata](https://docs.payroc.com/api/metadata).

## Other responses

- `400` — Invalid request
- `401` — Identity could not be verified
- `500` — An error has occured

---

[API](https://skmtc.dev/payroc/apis/schema.md) · [All operations](https://skmtc.dev/payroc/apis/schema/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/payroc/schema/revisions/1d9d3e305945/schema)