> ## 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.
# Update Webhook URL
> Set or update your webhook endpoint URL for receiving real-time event notifications. PUT /webhooks.
# Update Webhook URL
Set or update the webhook URL where FYATU will send event notifications. The URL must use HTTPS.
If this is the first time setting a webhook URL, a webhook secret will be automatically generated and returned in the response. **Store this secret securely** - it will not be shown again.
## Request
The HTTPS URL where webhooks will be sent. Set to `null` or empty string to disable webhooks.
```bash theme={null}
curl -X PUT https://api.fyatu.com/api/v3/webhooks \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"webhookUrl": "https://example.com/webhooks/fyatu"
}'
```
## Response
Whether the request was successful
The new webhook URL
Whether a webhook secret is configured
Whether webhooks are fully configured
The webhook secret (only returned when newly generated). **Store this securely!**
A reminder to store the secret securely
```json 200 (New Configuration) theme={null}
{
"success": true,
"status": 200,
"message": "Webhook URL updated successfully",
"data": {
"webhookUrl": "https://example.com/webhooks/fyatu",
"hasWebhookSecret": true,
"isConfigured": true,
"webhookSecret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"secretNote": "This is your webhook secret. Store it securely - it will not be shown again."
},
"meta": {
"requestId": "req_abc123xyz789",
"timestamp": "2026-01-15T10:30:00+00:00"
}
}
```
```json 200 (Update Existing) theme={null}
{
"success": true,
"status": 200,
"message": "Webhook URL updated successfully",
"data": {
"webhookUrl": "https://new-endpoint.example.com/webhooks",
"hasWebhookSecret": true,
"isConfigured": true
},
"meta": {
"requestId": "req_def456uvw123",
"timestamp": "2026-01-15T10:30:00+00:00"
}
}
```
```json 400 (Invalid URL) theme={null}
{
"success": false,
"status": 400,
"message": "Validation failed",
"error": {
"code": "VALIDATION_ERROR",
"details": [
{
"field": "webhookUrl",
"message": "Webhook URL must use HTTPS"
}
]
},
"meta": {
"requestId": "req_ghi789rst456",
"timestamp": "2026-01-15T10:30:00+00:00"
}
}
```
## Validation Rules
| Rule | Description |
| -------------- | ---------------------------------------- |
| HTTPS Required | Webhook URL must use `https://` protocol |
| Valid URL | Must be a properly formatted URL |
| Max Length | URL must be less than 500 characters |
## Disabling Webhooks
To disable webhooks, send an empty string or `null`:
```bash theme={null}
curl -X PUT https://api.fyatu.com/api/v3/webhooks \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"webhookUrl": null
}'
```
When you first configure a webhook URL, a secret will be generated. **Copy and store it immediately** as it will not be displayed again. You'll need this secret to verify webhook signatures.
## OpenAPI
````yaml v3/openapi.json PUT /webhooks
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:
put:
tags:
- Webhooks
summary: Update Webhook URL
description: >-
Update the webhook URL where event notifications will be sent. The URL
must be HTTPS.
operationId: updateWebhook
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookUpdateRequest'
example:
webhookUrl: https://example.com/webhooks/fyatu
responses:
'200':
description: Webhook URL updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookConfigResponse'
example:
success: true
status: 200
message: Webhook URL updated successfully
data:
webhookUrl: https://example.com/webhooks/fyatu
hasWebhookSecret: true
isConfigured: true
appType: ISSUING
createdAt: '2026-01-15T10:30:00+00:00'
updatedAt: '2026-01-15T10:30:00+00:00'
meta:
requestId: req_abc123xyz789
timestamp: '2026-01-15T10:30:00+00:00'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
status: 400
message: Webhook URL must use HTTPS
error:
code: INVALID_WEBHOOK_URL
meta:
requestId: req_abc123xyz789
timestamp: '2026-01-15T10:30:00+00:00'
'401':
$ref: '#/components/responses/Unauthorized'
security:
- BearerAuth: []
components:
schemas:
WebhookUpdateRequest:
type: object
required:
- webhookUrl
properties:
webhookUrl:
type: string
format: uri
description: >-
The HTTPS URL where webhook events will be sent. Must use HTTPS
protocol.
example: https://example.com/webhooks/fyatu
WebhookConfigResponse:
type: object
properties:
success:
type: boolean
example: true
status:
type: integer
example: 200
message:
type: string
data:
$ref: '#/components/schemas/WebhookConfig'
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'
WebhookConfig:
type: object
properties:
webhookUrl:
type: string
format: uri
description: The HTTPS URL where webhook events will be sent
hasWebhookSecret:
type: boolean
description: Whether a webhook secret is configured
isConfigured:
type: boolean
description: Whether a webhook URL is configured
appType:
type: string
enum:
- ISSUING
- COLLECTION
description: App type determines available events
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
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
````