> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Events

> Retrieve a list of events for the authenticated partner

# List Events

GET [https://api.baanx.com/v1/webhooks/events](https://api.baanx.com/v1/webhooks/events)
Retrieves a list of events for the authenticated partner.

## Overview

Events are notifications generated by the system that have been or will be delivered to your configured webhooks. Use this endpoint to monitor event processing status, identify failed events, and review recent activity.

## Authentication

This endpoint requires authentication via Bearer token:

```bash theme={null} theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Query Parameters

<ParamField query="status" type="string">
  Filter events by processing status.

  **Accepted values:** `pending`, `processing`, `completed`, `failed`, `skipped`
</ParamField>

<ParamField query="limit" type="integer" default={50}>
  Maximum number of events to return. Range: 1–100.
</ParamField>

### Request Example

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl -X GET "https://api.baanx.com/v1/webhooks/events?status=failed&limit=25" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript JavaScript theme={null} theme={null}
  const response = await fetch(
    'https://api.baanx.com/v1/webhooks/events?status=failed&limit=25',
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null} theme={null}
  import requests

  url = "https://api.baanx.com/v1/webhooks/events"
  headers = {
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
  }
  params = {
      "status": "failed",
      "limit": 25
  }

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```typescript TypeScript theme={null} theme={null}
  type EventStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'skipped';

  const listEvents = async (status?: EventStatus, limit = 50) => {
    const url = new URL('https://api.baanx.com/v1/webhooks/events');
    if (status) url.searchParams.set('status', status);
    url.searchParams.set('limit', String(limit));

    const response = await fetch(url.toString(), {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  };
  ```
</CodeGroup>

## Response

### 200 Success

<ResponseField name="total" type="integer">
  Total number of events matching the query
</ResponseField>

<ResponseField name="events" type="array">
  Array of event objects
</ResponseField>

<ResponseField name="events[].id" type="string (UUID)">
  Unique identifier for this event record
</ResponseField>

<ResponseField name="events[].eventId" type="string (UUID)">
  Business event identifier
</ResponseField>

<ResponseField name="events[].tenant" type="string">
  Partner tenant identifier
</ResponseField>

<ResponseField name="events[].eventType" type="string">
  Type of event (e.g., `kyc.status.changed`, `card.activated`, `transaction.cleared`)
</ResponseField>

<ResponseField name="events[].payload" type="object">
  Event payload data
</ResponseField>

<ResponseField name="events[].userId" type="string | null">
  Associated user ID, if applicable
</ResponseField>

<ResponseField name="events[].sourceService" type="string">
  Name of the service that generated this event
</ResponseField>

<ResponseField name="events[].status" type="string">
  Current processing status: `pending`, `processing`, `completed`, `failed`, or `skipped`
</ResponseField>

<ResponseField name="events[].createdAt" type="string (ISO 8601)">
  Timestamp when the event was created
</ResponseField>

<ResponseField name="events[].processedAt" type="string (ISO 8601) | null">
  Timestamp when the event was processed (`null` if not yet processed)
</ResponseField>

<ResponseField name="events[].queuedAt" type="string (ISO 8601) | null">
  Timestamp when the event was queued for delivery
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null} theme={null}
  {
    "total": 100,
    "events": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "eventId": "660e8400-e29b-41d4-a716-446655440001",
        "tenant": "partner-name",
        "eventType": "kyc.status.changed",
        "payload": {
          "userId": "user-123",
          "status": "approved"
        },
        "userId": "user-123",
        "sourceService": "kyc-service",
        "status": "completed",
        "createdAt": "2025-12-29T10:00:00.000Z",
        "processedAt": "2025-12-29T10:00:05.000Z",
        "queuedAt": "2025-12-29T10:00:01.000Z"
      }
    ]
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 401 - Unauthorized theme={null} theme={null}
  {
    "message": "Not authenticated"
  }
  ```

  ```json 403 - Forbidden theme={null} theme={null}
  {
    "message": "Not authorized"
  }
  ```

  ```json 503 - Service Unavailable theme={null} theme={null}
  {
    "message": "Notification service is not configured for this environment"
  }
  ```
</ResponseExample>

## Related Endpoints

* `GET /v1/webhooks/events/{eventId}/status` - Get status of a specific event
* `GET /v1/webhooks/events/{eventId}/logs` - View delivery logs for a specific event
* `POST /v1/webhooks/events/{eventId}/retry` - Retry delivery of a failed event