# Webhook Events and Subscriptions

## Overview

Peach supports various event types across different categories that you can subscribe to. For example, subscribing to the `autopay.schedule.changed `allows you to receive a notification when an autopay schedule changes.

## Retrieving Events

To retrieve events, call the Retrieve Events request and specify query parameters for the events.

### Query Parameters

The following query parameters can be used to filter and customize your event retrieval:

* `limit` (integer, 1-100, default: 25): The maximum count of results to retrieve.
* `startingAfter` (string): Return results starting after the provided object identifier.
* `endingBefore` (string): Return results ending before the provided object identifier.
* `sortBy` (array of strings): The data attributes by which to sort the results.
* `personId` (string): Filter by a Borrower's unique identifier.
* `periodId` (string): Limit results to a specific periodId.
* `loanId` (string): Filter by Loan's unique identifier.
* `caseId` (string): Filter by case's object unique identifier.
* `transactionId` (string): Filter by transaction's unique identifier.
* `createdAtFrom` (string, date-time): Get events created at or after the specified time.
* `createdAtTo` (string, date-time): Get events created before the specified time.
* `effectiveAtFrom` (string, date-time): Get events effective at or after the specified time.
* `effectiveAtTo` (string, date-time): Get events effective before the specified time.
* `accrualDate` (string, date): Get events by matching accrual date (for AccrueInterestEvent only).
* `includeDeleted` (boolean, default: true): Include events that have been deleted.
* `events` (string): A comma-separated list of event names to return. Use wildcards for broader matching.
* `excludeEvents` (string): A comma-separated list of event names to exclude from the response.
* `webhookId` (string): The webhook ID to filter events by.
* `creatingMessageIds` (array of strings): A comma-separated list of creatingMessageIds to return.


### Example Request

The following request retrieves up to 25 of the most recent webhook events.


```bash
curl --location 'https://api.peach.finance/api/events?limit=25' \
--header 'Accept: application/json' \
--header 'X-API-KEY: <YOUR-API-KEY>'
```

## Response

### Response Structure


```json
{
    "status": 200,
    "data": [/* Array of event objects */],
    "total": <total_count>,
    "count": <returned_count>,
    "nextUrl": <url_for_next_page>,
    "previousUrl": <url_for_previous_page>
}
```

### Event Object Properties

| Property | Type | Description |
|  --- | --- | --- |
| id | string | Unique identifier for the event |
| eventType | string | Type of event (e.g., "payment.initiated", "loan.activated") |
| eventClass | string | Class of the event (e.g., "PaymentInitiatedEvent") |
| effectiveAt | string | ISO 8601 timestamp when the event took effect |
| createdAt | string | ISO 8601 timestamp when the event was created |
| loanId | string | Associated loan ID (if applicable) |
| personId | string | Associated person ID (if applicable) |
| paymentInstrumentId | string | Associated payment instrument ID (if applicable) |
| transactionId | string | Associated transaction ID (if applicable) |


### Pagination

The response includes URLs for the next and previous pages of results:

- `nextUrl`: URL to retrieve the next page of events
- `previousUrl`: URL to retrieve the previous page of events


### Example Response


```json
{
    "status": 200,
    "data": [
        {
            "id": "EV-L9BN-5J52",
            "eventType": "payment.instrument.deactivated",
            "eventClass": "PaymentInstrumentDeactivatedEvent",
            "effectiveAt": "2020-03-18T21:08:03.736597+00:00",
            "createdAt": "2020-03-19T08:23:52.545701+00:00",
            "paymentInstrumentId": "PT-L9BN-Z5B5"
        }
        // ... additional events
    ],
    "total": 10000,
    "count": 25,
    "nextUrl": "https://sandboxapi.peach.finance/api/events?limit=25&startingAfter=EV-7NBP-61KG",
    "previousUrl": "https://sandboxapi.peach.finance/api/events?limit=25&endingBefore=EV-L9BN-5J52"
}
```

## Common Event Types

- `payment.initiated`: Payment initiation
- `payment.succeeded`: Successful payment completion
- `loan.activated`: Loan activation
- `loan.originated`: Loan origination
- `payment.instrument.deactivated`: Payment instrument deactivation


See the full list of events [here](/api-docs/api-public/events)