---
title: "Create event subscription"
method: POST
path: "/event-subscriptions"
tags: ["eventSubscriptions"]
---

# Create event subscription

`POST /event-subscriptions`

Use this method to create an event subscription that we use to notify you when an event occurs, for example, when we change the status of a processing account.  

In the request, include the events that you want to subscribe to and the public endpoint that we send event notifications to. For a complete list of events that you can subscribe to, go to [Events List](https://docs.payroc.com/knowledge/events/events-list).  

In the response, our gateway returns the id of the event subscription, which you can use to perform follow-on actions.

## Headers

- `Authorization` string, required
- `Idempotency-Key` string, uuid, required

## Request body

- EventSubscription
  - `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).

## Response `201`

Successful request. We created the event subscription.

- EventSubscription
  - `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` — Validation error
- `401` — Identity could not be verified
- `406` — Not acceptable
- `409` — Conflict
- `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)