> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.payroc.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.payroc.com/_mcp/server.

# Event subscriptions

> Subscribe to account changes and handle webhook notifications sent by our gateway.

Event subscriptions are a feature of our API that you can subscribe to so that we notify you about changes to an account, for example, when we change the status of a processing account.

**Note:** For a list of the events that you can subscribe to, go to [Events list](/knowledge/events/events-list).

## How it works

The following diagram shows how to subscribe to an event and how to handle an event.

```mermaid
sequenceDiagram
    participant YI as Your integration
    participant GW as Gateway

    rect rgba(0, 81, 194, 0.4)
        Note over YI,GW: Subscribe to events
        YI->>GW: 1. Create an event subscription
        Note over GW: 2. Gateway creates the event subscription
        GW-->>YI: 3. Return a response
    end

    rect rgba(0, 224, 184, 0.3)
        Note over YI,GW: Handle event webhook requests
        Note over GW: 1. A change on the account triggers an event notification
        GW->>YI: 2. Send a webhook request
        Note over YI: 3. Receive the webhook request
        YI->>GW: 4. Return a 200 response
    end
```

### Subscribe to events

1. Create an event subscription and send it to our gateway.
2. Our gateway creates the event subscription.
3. Our gateway sends you a response to confirm that we have created the subscription.

### Handle event notifications

1. We make a change to an account and trigger an event notification.
2. Our gateway sends a

   webhook

   to your endpoint.
3. Your server returns a 200 response to confirm that you have received the webhook.

## Your integration journey

To add event notifications to your integration, complete the following steps:

1. Create an event subscription with our API.
2. Handle the webhook.

## Guides

#### [Event notifications](/guides/board-merchants/event-subscriptions/create-an-event-subscription)

Add event notifications to your integration.