> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Webhook Events
> List all available webhook event types — card, cardholder, collection, payout, and refund events. GET /webhooks/events.
# List Webhook Events
Returns a list of all webhook event types that can be sent to your app. The events available depend on your app type (Issuing or Collection).
## Request
```bash theme={null}
curl -X GET https://api.fyatu.com/api/v3/webhooks/events \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
## Response
Whether the request was successful
Your app type: `ISSUING` or `COLLECTION`
List of available webhook events
The event type identifier (e.g., `card.created`)
Human-readable event name
Event category (card, cardholder, collection, payout, refund)
Description of when this event is triggered
Total number of available events
```json 200 (Issuing App) theme={null}
{
"success": true,
"status": 200,
"message": "Webhook events retrieved",
"data": {
"appType": "ISSUING",
"events": [
{
"event": "card.created",
"name": "Card Created",
"category": "card",
"description": "Triggered when a new card is created for a cardholder"
},
{
"event": "card.funded",
"name": "Card Funded",
"category": "card",
"description": "Triggered when funds are added to a card"
},
{
"event": "card.transaction.approved",
"name": "Transaction Approved",
"category": "card",
"description": "Triggered when a card transaction is approved"
},
{
"event": "cardholder.created",
"name": "Cardholder Created",
"category": "cardholder",
"description": "Triggered when a new cardholder is created"
},
{
"event": "cardholder.kyc_approved",
"name": "KYC Approved",
"category": "cardholder",
"description": "Triggered when KYC verification is approved"
}
],
"total": 22
},
"meta": {
"requestId": "req_abc123xyz789",
"timestamp": "2026-01-15T10:30:00+00:00"
}
}
```
```json 200 (Collection App) theme={null}
{
"success": true,
"status": 200,
"message": "Webhook events retrieved",
"data": {
"appType": "COLLECTION",
"events": [
{
"event": "collection.initiated",
"name": "Collection Initiated",
"category": "collection",
"description": "Triggered when a payment collection is initiated"
},
{
"event": "collection.received",
"name": "Collection Received",
"category": "collection",
"description": "Triggered when payment is successfully received"
},
{
"event": "payout.completed",
"name": "Payout Completed",
"category": "payout",
"description": "Triggered when a payout is successfully completed"
},
{
"event": "refund.completed",
"name": "Refund Completed",
"category": "refund",
"description": "Triggered when a refund is completed"
}
],
"total": 10
},
"meta": {
"requestId": "req_def456uvw123",
"timestamp": "2026-01-15T10:30:00+00:00"
}
}
```
## Event Categories
### Issuing App Events
| Category | Events |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **card** | `card.created`, `card.failed`, `card.funded`, `card.funding_failed`, `card.unloaded`, `card.unloading_failed`, `card.frozen`, `card.unfrozen`, `card.terminated`, `card.termination_refund`, `card.termination_refund_post`, `card.replaced`, `card.transaction.approved`, `card.transaction.declined`, `card.transaction.reversed`, `card.transaction.cross_border_fee`, `card.transaction.decline_fee_domestic`, `card.transaction.decline_fee_international`, `card.maintenance_fee_paid`, `card.negative_balance`, `card.delete_warning`, `card.tokenization_otp`, `card.3ds_otp` |
| **cardholder** | `cardholder.created`, `cardholder.updated`, `cardholder.kyc_submitted`, `cardholder.kyc_approved`, `cardholder.kyc_rejected`, `cardholder.suspended`, `cardholder.activated` |
### Collection App Events
| Category | Events |
| -------------- | ---------------------------------------------------------------------------------------- |
| **collection** | `collection.initiated`, `collection.received`, `collection.failed`, `collection.expired` |
| **payout** | `payout.initiated`, `payout.completed`, `payout.failed` |
| **refund** | `refund.initiated`, `refund.completed`, `refund.failed` |
## Use Cases
* Build a dynamic webhook handler that discovers available events
* Display available events in your admin dashboard
* Validate event types before testing
## OpenAPI
````yaml v3/openapi.json GET /webhooks/events
openapi: 3.1.0
info:
title: FYATU API v3
description: >-
FYATU API v3 with JWT authentication for Collections, Payouts, and Card
Issuing.
version: 3.0.0
contact:
name: FYATU Support
url: https://fyatu.com
email: support@fyatu.com
servers:
- url: https://api.fyatu.com/api/v3
description: Production
security: []
tags:
- name: Authentication
description: JWT token management endpoints
- name: Account
description: Business account, wallet, and address management
- name: Collections
description: Accept payments from customers via checkout sessions
- name: Refunds
description: Issue refunds for completed collections
- name: Payouts
description: Send money to Fyatu account holders
- name: Cardholders
description: Cardholder management for card issuing programs
- name: Cards
description: Issue, fund, freeze, and manage virtual cards
- name: Webhooks
description: Webhook configuration and management
paths:
/webhooks/events:
get:
tags:
- Webhooks
summary: List Webhook Events
description: >-
Returns a list of all webhook event types that can be sent to your app.
The events available depend on your app type (Issuing or Collection).
operationId: listWebhookEvents
responses:
'200':
description: Webhook events retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEventsResponse'
example:
success: true
status: 200
message: Webhook events retrieved
data:
appType: ISSUING
events:
- event: card.created
name: Card Created
category: card
description: Triggered when a new card is created for a cardholder
- event: card.funded
name: Card Funded
category: card
description: Triggered when funds are added to a card
- event: card.transaction.approved
name: Transaction Approved
category: card
description: Triggered when a card transaction is approved
- event: cardholder.created
name: Cardholder Created
category: cardholder
description: Triggered when a new cardholder is created
- event: cardholder.kyc_approved
name: KYC Approved
category: cardholder
description: Triggered when KYC verification is approved
total: 22
meta:
requestId: req_abc123xyz789
timestamp: '2026-01-15T10:30:00+00:00'
'401':
$ref: '#/components/responses/Unauthorized'
security:
- BearerAuth: []
components:
schemas:
WebhookEventsResponse:
type: object
properties:
success:
type: boolean
example: true
status:
type: integer
example: 200
message:
type: string
data:
type: object
properties:
appType:
type: string
enum:
- ISSUING
- COLLECTION
events:
type: array
items:
$ref: '#/components/schemas/WebhookEvent'
total:
type: integer
description: Total number of available events
meta:
$ref: '#/components/schemas/Meta'
WebhookEvent:
type: object
properties:
event:
type: string
description: Event type identifier
example: card.created
name:
type: string
description: Human-readable event name
example: Card Created
category:
type: string
description: Event category
example: card
description:
type: string
description: Description of when this event is triggered
Meta:
type: object
properties:
requestId:
type: string
description: Unique request ID for tracking
example: req_abc123def456
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp of the response
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
status:
type: integer
example: 401
message:
type: string
example: Invalid credentials
error:
$ref: '#/components/schemas/Error'
meta:
$ref: '#/components/schemas/Meta'
Error:
type: object
properties:
code:
type: string
description: Error code for programmatic handling
example: AUTH_INVALID_CREDENTIALS
details:
type: array
items:
$ref: '#/components/schemas/ValidationError'
description: Validation error details (for VALIDATION_ERROR)
ValidationError:
type: object
properties:
field:
type: string
description: Field that failed validation
example: appId
message:
type: string
description: Validation error message
example: AppId is required
responses:
Unauthorized:
description: Authentication required or token invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
status: 401
message: Unable to identify business
error:
code: AUTH_TOKEN_INVALID
meta:
requestId: req_abc123
timestamp: '2026-01-05T10:30:00+00:00'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT access token obtained from /auth/token
````