> ## 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.
# Test Webhook
> Send a test webhook event to verify your endpoint is receiving and processing notifications correctly. POST /webhooks/test.
# Test Webhook
Send a test webhook event to your configured endpoint. This is useful for:
* Verifying your webhook handler is working correctly
* Testing signature verification
* Developing and debugging your integration
**All test data is simulated** and clearly marked with `TEST_` prefixes. These are not real transactions, cards, or cardholders. The only real values are:
* Your `appId`
* The webhook signature (signed with your real webhook secret)
## Request
The event type to simulate. Use [List Events](/v3/api-reference/webhooks/events) to see available events for your app type.
```bash theme={null}
curl -X POST https://api.fyatu.com/api/v3/webhooks/test \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"event": "card.created"
}'
```
## Response
Whether the request was successful
The event type that was sent
The URL where the webhook was sent
Whether the webhook was delivered successfully (HTTP 200 response)
The exact payload that was sent to your webhook endpoint
Reminder that this is test data
Information about how the webhook was signed
Error message if delivery failed (only present on failure)
```json 200 (Delivered Successfully) theme={null}
{
"success": true,
"status": 200,
"message": "Test webhook delivered successfully",
"data": {
"event": "card.created",
"webhookUrl": "https://example.com/webhooks/fyatu",
"delivered": true,
"testData": {
"appId": "D0H6R7Z6R1C2N5O5",
"timestamp": "2026-01-15T10:30:00+00:00",
"_test": true,
"_note": "This is simulated test data for development purposes only.",
"cardId": "TEST_CRD8A7B6C5D4E3F2",
"cardholderId": "TEST_CH4a3b2c1d5e6f",
"type": "VIRTUAL",
"brand": "MASTERCARD",
"currency": "USD",
"last4": "4532",
"status": "ACTIVE"
},
"note": "This is TEST DATA for development purposes only. All IDs and values are simulated and do not represent real transactions.",
"signature": {
"algorithm": "HMAC-SHA256",
"signedWith": "Your webhook secret",
"verifyUsing": "hash_hmac(\"sha256\", json_encode($data), $webhookSecret)"
}
},
"meta": {
"requestId": "req_abc123xyz789",
"timestamp": "2026-01-15T10:30:00+00:00"
}
}
```
```json 200 (Delivery Failed) theme={null}
{
"success": true,
"status": 200,
"message": "Test webhook delivery attempted but failed",
"data": {
"event": "card.created",
"webhookUrl": "https://example.com/webhooks/fyatu",
"delivered": false,
"testData": {
"appId": "D0H6R7Z6R1C2N5O5",
"timestamp": "2026-01-15T10:30:00+00:00",
"_test": true,
"_note": "This is simulated test data for development purposes only.",
"cardId": "TEST_CRD8A7B6C5D4E3F2",
"cardholderId": "TEST_CH4a3b2c1d5e6f",
"type": "VIRTUAL",
"brand": "MASTERCARD",
"currency": "USD",
"last4": "4532",
"status": "ACTIVE"
},
"note": "This is TEST DATA for development purposes only. All IDs and values are simulated and do not represent real transactions.",
"signature": {
"algorithm": "HMAC-SHA256",
"signedWith": "Your webhook secret",
"verifyUsing": "hash_hmac(\"sha256\", json_encode($data), $webhookSecret)"
},
"error": "Webhook delivery failed. Check that your endpoint is accessible and returns HTTP 200."
},
"meta": {
"requestId": "req_def456uvw123",
"timestamp": "2026-01-15T10:30:00+00:00"
}
}
```
```json 400 (Webhook Not Configured) theme={null}
{
"success": false,
"status": 400,
"message": "Webhook URL not configured. Set a webhook URL first.",
"error": {
"code": "WEBHOOK_NOT_CONFIGURED"
},
"meta": {
"requestId": "req_ghi789rst456",
"timestamp": "2026-01-15T10:30:00+00:00"
}
}
```
## Test Payload Structure
All test webhooks follow the standard webhook format:
```json theme={null}
{
"event": "card.created",
"version": "2.0",
"sign": "hmac_sha256_signature_here",
"data": {
"appId": "YOUR_REAL_APP_ID",
"timestamp": "2026-01-15T10:30:00+00:00",
"_test": true,
"_note": "This is simulated test data for development purposes only.",
// ... event-specific test data with TEST_ prefixes
}
}
```
## Identifying Test Webhooks
Test webhooks can be identified by:
1. The `_test: true` field in the data payload
2. The `_note` field explaining it's test data
3. All IDs prefixed with `TEST_`
Your webhook handler should check for `_test: true` if you want to handle test webhooks differently in production.
## Available Test Events
### Issuing App Events
```bash theme={null}
# Card events
card.created
card.funded
card.unloaded
card.frozen
card.unfrozen
card.terminated
card.replaced
card.maintenance_fee_paid
# Card transaction events
card.transaction.approved
card.transaction.declined
card.transaction.reversed
card.transaction.cross_border_fee
card.transaction.decline_fee_domestic
card.transaction.decline_fee_international
# Cardholder events
cardholder.created
cardholder.updated
cardholder.kyc_submitted
cardholder.kyc_approved
cardholder.kyc_rejected
cardholder.suspended
cardholder.activated
```
### Collection App Events
```bash theme={null}
# Collection events
collection.initiated
collection.received
collection.failed
collection.expired
# Payout events
payout.initiated
payout.completed
payout.failed
# Refund events
refund.initiated
refund.completed
refund.failed
```
## Verifying the Signature
Even test webhooks are signed with your real webhook secret. Use this to verify your signature verification code:
```javascript theme={null}
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(JSON.stringify(payload.data))
.digest('hex');
return signature === expectedSignature;
}
// In your webhook handler
app.post('/webhooks/fyatu', (req, res) => {
const { event, sign, data } = req.body;
if (!verifyWebhook(req.body, sign, process.env.WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
// Check if it's a test webhook
if (data._test) {
console.log('Received test webhook:', event);
return res.status(200).send('Test webhook received');
}
// Process real webhook...
res.status(200).send('OK');
});
```
Your webhook endpoint must return HTTP 200 within 10 seconds for the delivery to be considered successful.
## OpenAPI
````yaml v3/openapi.json POST /webhooks/test
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/test:
post:
tags:
- Webhooks
summary: Test Webhook
description: >-
Send a test webhook event to your configured endpoint. This is useful
for verifying your webhook handler is working correctly, testing
signature verification, and developing your integration.
operationId: testWebhook
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookTestRequest'
example:
event: card.created
responses:
'200':
description: Test webhook sent
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookTestResponse'
examples:
delivered:
summary: Delivered Successfully
value:
success: true
status: 200
message: Test webhook delivered successfully
data:
event: card.created
webhookUrl: https://example.com/webhooks/fyatu
delivered: true
testData:
appId: D0H6R7Z6R1C2N5O5
timestamp: '2026-01-15T10:30:00+00:00'
_test: true
_note: >-
This is simulated test data for development purposes
only.
cardId: TEST_CRD8A7B6C5D4E3F2
cardholderId: TEST_ch_abc123def456
type: VIRTUAL
brand: MASTERCARD
currency: USD
last4: '4532'
status: ACTIVE
note: >-
This is TEST DATA for development purposes only. All IDs
and values are simulated and do not represent real
transactions.
signature:
algorithm: HMAC-SHA256
signedWith: Your webhook secret
verifyUsing: >-
hash_hmac("sha256", json_encode($data),
$webhookSecret)
meta:
requestId: req_abc123xyz789
timestamp: '2026-01-15T10:30:00+00:00'
failed:
summary: Delivery Failed
value:
success: true
status: 200
message: Test webhook delivery attempted but failed
data:
event: card.created
webhookUrl: https://example.com/webhooks/fyatu
delivered: false
error: >-
Webhook delivery failed. Check that your endpoint is
accessible and returns HTTP 200.
meta:
requestId: req_def456uvw123
timestamp: '2026-01-15T10:30:00+00:00'
'400':
description: Webhook not configured
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
status: 400
message: Webhook URL not configured. Set a webhook URL first.
error:
code: WEBHOOK_NOT_CONFIGURED
meta:
requestId: req_ghi789rst456
timestamp: '2026-01-15T10:30:00+00:00'
'401':
$ref: '#/components/responses/Unauthorized'
security:
- BearerAuth: []
components:
schemas:
WebhookTestRequest:
type: object
required:
- event
properties:
event:
type: string
description: >-
The event type to simulate. Use List Events endpoint to see
available events.
example: card.created
WebhookTestResponse:
type: object
properties:
success:
type: boolean
example: true
status:
type: integer
example: 200
message:
type: string
data:
type: object
properties:
event:
type: string
description: Event type that was sent
webhookUrl:
type: string
description: URL where webhook was sent
delivered:
type: boolean
description: Whether delivery was successful (HTTP 200)
testData:
type: object
description: Exact payload sent to webhook endpoint
note:
type: string
description: Reminder that this is test data
signature:
type: object
properties:
algorithm:
type: string
example: HMAC-SHA256
signedWith:
type: string
example: Your webhook secret
verifyUsing:
type: string
description: Code example for verification
error:
type: string
description: Error message if delivery failed
meta:
$ref: '#/components/schemas/Meta'
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'
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
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
````