Create a webhook
curl --request POST \
--url https://api.fyatu.com/api/v3.20/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://yourapp.com/webhooks/fyatu",
"events": [
"CARD_ISSUED",
"CARD_FUNDED",
"TRANSACTION_AUTHORIZED",
"TRANSACTION_DECLINED"
],
"description": "Production card events"
}
'import requests
url = "https://api.fyatu.com/api/v3.20/webhooks"
payload = {
"url": "https://yourapp.com/webhooks/fyatu",
"events": ["CARD_ISSUED", "CARD_FUNDED", "TRANSACTION_AUTHORIZED", "TRANSACTION_DECLINED"],
"description": "Production card events"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://yourapp.com/webhooks/fyatu',
events: ['CARD_ISSUED', 'CARD_FUNDED', 'TRANSACTION_AUTHORIZED', 'TRANSACTION_DECLINED'],
description: 'Production card events'
})
};
fetch('https://api.fyatu.com/api/v3.20/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.fyatu.com/api/v3.20/webhooks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://yourapp.com/webhooks/fyatu',
'events' => [
'CARD_ISSUED',
'CARD_FUNDED',
'TRANSACTION_AUTHORIZED',
'TRANSACTION_DECLINED'
],
'description' => 'Production card events'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.fyatu.com/api/v3.20/webhooks"
payload := strings.NewReader("{\n \"url\": \"https://yourapp.com/webhooks/fyatu\",\n \"events\": [\n \"CARD_ISSUED\",\n \"CARD_FUNDED\",\n \"TRANSACTION_AUTHORIZED\",\n \"TRANSACTION_DECLINED\"\n ],\n \"description\": \"Production card events\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.fyatu.com/api/v3.20/webhooks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://yourapp.com/webhooks/fyatu\",\n \"events\": [\n \"CARD_ISSUED\",\n \"CARD_FUNDED\",\n \"TRANSACTION_AUTHORIZED\",\n \"TRANSACTION_DECLINED\"\n ],\n \"description\": \"Production card events\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fyatu.com/api/v3.20/webhooks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://yourapp.com/webhooks/fyatu\",\n \"events\": [\n \"CARD_ISSUED\",\n \"CARD_FUNDED\",\n \"TRANSACTION_AUTHORIZED\",\n \"TRANSACTION_DECLINED\"\n ],\n \"description\": \"Production card events\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"status": 201,
"message": "Webhook created",
"data": {
"webhookId": "whk_01HXYZ7777ABCDEF4444",
"url": "https://yourapp.com/webhooks/fyatu",
"description": "Production card events",
"events": [
"CARD_ISSUED",
"CARD_FUNDED",
"TRANSACTION_AUTHORIZED",
"TRANSACTION_DECLINED"
],
"status": "ACTIVE",
"secretPrefix": "whsec_a1b2c3",
"failureCount": 0,
"lastDeliveryAt": null,
"lastDeliveryStatus": null,
"totalDeliveries": 0,
"totalFailures": 0,
"createdAt": "2026-05-22T09:00:00Z",
"updatedAt": "2026-05-22T09:00:00Z"
},
"secret": "whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
"meta": {
"requestId": "req_a1b2c3d4e5f6a7b8c9d0e1f2",
"platform": "Fyatu CaaS",
"timestamp": "2026-05-22T09:00:00Z"
}
}Webhooks
Create Webhook
Register a new webhook endpoint to receive events from your business. POST /webhooks. Requires webhooks:write scope.
POST
/
webhooks
Create a webhook
curl --request POST \
--url https://api.fyatu.com/api/v3.20/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://yourapp.com/webhooks/fyatu",
"events": [
"CARD_ISSUED",
"CARD_FUNDED",
"TRANSACTION_AUTHORIZED",
"TRANSACTION_DECLINED"
],
"description": "Production card events"
}
'import requests
url = "https://api.fyatu.com/api/v3.20/webhooks"
payload = {
"url": "https://yourapp.com/webhooks/fyatu",
"events": ["CARD_ISSUED", "CARD_FUNDED", "TRANSACTION_AUTHORIZED", "TRANSACTION_DECLINED"],
"description": "Production card events"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://yourapp.com/webhooks/fyatu',
events: ['CARD_ISSUED', 'CARD_FUNDED', 'TRANSACTION_AUTHORIZED', 'TRANSACTION_DECLINED'],
description: 'Production card events'
})
};
fetch('https://api.fyatu.com/api/v3.20/webhooks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.fyatu.com/api/v3.20/webhooks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://yourapp.com/webhooks/fyatu',
'events' => [
'CARD_ISSUED',
'CARD_FUNDED',
'TRANSACTION_AUTHORIZED',
'TRANSACTION_DECLINED'
],
'description' => 'Production card events'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.fyatu.com/api/v3.20/webhooks"
payload := strings.NewReader("{\n \"url\": \"https://yourapp.com/webhooks/fyatu\",\n \"events\": [\n \"CARD_ISSUED\",\n \"CARD_FUNDED\",\n \"TRANSACTION_AUTHORIZED\",\n \"TRANSACTION_DECLINED\"\n ],\n \"description\": \"Production card events\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.fyatu.com/api/v3.20/webhooks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://yourapp.com/webhooks/fyatu\",\n \"events\": [\n \"CARD_ISSUED\",\n \"CARD_FUNDED\",\n \"TRANSACTION_AUTHORIZED\",\n \"TRANSACTION_DECLINED\"\n ],\n \"description\": \"Production card events\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fyatu.com/api/v3.20/webhooks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://yourapp.com/webhooks/fyatu\",\n \"events\": [\n \"CARD_ISSUED\",\n \"CARD_FUNDED\",\n \"TRANSACTION_AUTHORIZED\",\n \"TRANSACTION_DECLINED\"\n ],\n \"description\": \"Production card events\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"status": 201,
"message": "Webhook created",
"data": {
"webhookId": "whk_01HXYZ7777ABCDEF4444",
"url": "https://yourapp.com/webhooks/fyatu",
"description": "Production card events",
"events": [
"CARD_ISSUED",
"CARD_FUNDED",
"TRANSACTION_AUTHORIZED",
"TRANSACTION_DECLINED"
],
"status": "ACTIVE",
"secretPrefix": "whsec_a1b2c3",
"failureCount": 0,
"lastDeliveryAt": null,
"lastDeliveryStatus": null,
"totalDeliveries": 0,
"totalFailures": 0,
"createdAt": "2026-05-22T09:00:00Z",
"updatedAt": "2026-05-22T09:00:00Z"
},
"secret": "whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
"meta": {
"requestId": "req_a1b2c3d4e5f6a7b8c9d0e1f2",
"platform": "Fyatu CaaS",
"timestamp": "2026-05-22T09:00:00Z"
}
}Overview
Registers a new webhook endpoint for your business. The endpoint will receive HTTP POST requests from FYATU whenever the subscribed events occur. Your endpoint must respond with HTTP2xx within 30 seconds.
The response includes a secret field at the top level containing the raw webhook signing secret. This is shown exactly once — store it securely in an environment variable. It cannot be retrieved again; if lost, delete the webhook and create a new one.
Request Body
| Field | Type | Required | Constraint | Description |
|---|---|---|---|---|
url | string | Yes | https:// required for LIVE | Your endpoint URL |
events | array | Yes | 1–20 event types | List of event types to subscribe to |
description | string | No | Max 255 chars | Internal label for this endpoint |
Available Events
Subscribe to one or more events from this list: Account events:ACCOUNT_LOW_BALANCE, ACCOUNT_WITHDRAWAL_INITIATED, ACCOUNT_WITHDRAWAL_COMPLETED, ACCOUNT_WITHDRAWAL_FAILED
Billing events: BILLING_INVOICE_CREATED, BILLING_INVOICE_PAID, BILLING_INVOICE_OVERDUE, BILLING_DEPOSIT_DETECTED, BILLING_DEPOSIT_CONFIRMED
Cardholder events: CARDHOLDER_CREATED, CARDHOLDER_SUSPENDED, CARDHOLDER_REACTIVATED, CARDHOLDER_DELETED, CARDHOLDER_KYC_APPROVED, CARDHOLDER_KYC_REJECTED
Card events: CARD_ISSUED, CARD_FROZEN, CARD_UNFROZEN, CARD_TERMINATED, CARD_FUNDED, CARD_UNLOADED, CARD_FUND_FAILED, CARD_UNLOAD_FAILED, CARD_3DS_OTP, CARD_TOKENIZATION_OTP, CARD_AUTHORIZATION
Transaction events: TRANSACTION_AUTHORIZED, TRANSACTION_CLEARED, TRANSACTION_REVERSED, TRANSACTION_DECLINED, TRANSACTION_FEE
Example
curl -X POST https://api.fyatu.com/api/v3.20/webhooks \
-H "Authorization: Bearer $FYATU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourapp.com/webhooks/fyatu",
"description": "Production card events",
"events": [
"CARD_ISSUED",
"CARD_FUNDED",
"TRANSACTION_AUTHORIZED",
"TRANSACTION_DECLINED",
"CARDHOLDER_KYC_APPROVED",
"CARDHOLDER_KYC_REJECTED"
]
}'
const resp = await fetch('https://api.fyatu.com/api/v3.20/webhooks', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.FYATU_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
url: 'https://yourapp.com/webhooks/fyatu',
description: 'Production card events',
events: [
'CARD_ISSUED',
'CARD_FUNDED',
'TRANSACTION_AUTHORIZED',
'TRANSACTION_DECLINED',
'CARDHOLDER_KYC_APPROVED',
'CARDHOLDER_KYC_REJECTED'
]
})
});
const body = await resp.json();
console.log('Webhook ID:', body.data.webhookId);
console.log('Secret:', body.secret); // At top level — store this immediately!
import os, requests
resp = requests.post(
'https://api.fyatu.com/api/v3.20/webhooks',
headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'},
json={
'url': 'https://yourapp.com/webhooks/fyatu',
'description': 'Production card events',
'events': [
'CARD_ISSUED', 'CARD_FUNDED',
'TRANSACTION_AUTHORIZED', 'TRANSACTION_DECLINED',
'CARDHOLDER_KYC_APPROVED', 'CARDHOLDER_KYC_REJECTED'
]
}
)
body = resp.json()
print('Webhook ID:', body['data']['webhookId'])
print('Secret:', body['secret']) # At top level — store this!
Success Response (201)
The
secret is returned at the top level of the response envelope (a sibling of data), not inside data. Copy it to your environment variable store immediately. Future calls to GET /webhooks/{id} return only secretPrefix (first 12 characters) for identification.{
"success": true,
"status": 201,
"message": "Webhook created",
"data": {
"webhookId": "whk_01HXYZ7777ABCDEF4444",
"url": "https://yourapp.com/webhooks/fyatu",
"description": "Production card events",
"events": [
"CARD_ISSUED",
"CARD_FUNDED",
"TRANSACTION_AUTHORIZED",
"TRANSACTION_DECLINED",
"CARDHOLDER_KYC_APPROVED",
"CARDHOLDER_KYC_REJECTED"
],
"status": "ACTIVE",
"secretPrefix": "whsec_a1b2c3d4e5f6",
"failureCount": 0,
"lastDeliveryAt": null,
"lastDeliveryStatus": null,
"totalDeliveries": 0,
"totalFailures": 0,
"createdAt": "2026-05-22T09:00:00Z",
"updatedAt": "2026-05-22T09:00:00Z"
},
"secret": "whsec_a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef01234567",
"meta": {
"requestId": "req_01HXY123456ABCDEF",
"platform": "Fyatu CaaS",
"timestamp": "2026-05-22T09:00:00Z"
}
}
Error Codes
| Code | HTTP | Cause |
|---|---|---|
WEBHOOK_LIMIT_REACHED | 422 | Maximum of 10 webhook endpoints per environment |
WEBHOOK_HTTPS_REQUIRED | 422 | LIVE environment requires an https:// URL |
INVALID_EVENT_TYPE | 422 | One or more event types in events are not recognised |
VALIDATION_ERROR | 422 | Missing or invalid fields |
INSUFFICIENT_SCOPE | 403 | Key lacks webhooks:write scope |
Authorizations
API key from the FYATU CaaS portal. Pass as Authorization: Bearer <key>.
Body
application/json
Example:
"https://yourapp.com/webhooks/fyatu"
Required array length:
1 - 20 elementsAvailable options:
CARD_ISSUED, CARD_FROZEN, CARD_UNFROZEN, CARD_TERMINATED, CARD_TERMINATION_REFUND, CARD_TERMINATION_REFUND_POST, CARD_POST_REFUND_CHARGE, CARD_FUNDED, CARD_UNLOADED, CARD_FUND_FAILED, CARD_UNLOAD_FAILED, CARDHOLDER_CREATED, CARDHOLDER_UPDATED, CARDHOLDER_SUSPENDED, CARDHOLDER_REACTIVATED, CARDHOLDER_TERMINATED, CARDHOLDER_KYC_SUBMITTED, CARDHOLDER_KYC_SUBMISSION_FAILED, CARDHOLDER_KYC_APPROVED, CARDHOLDER_KYC_REJECTED, CARDHOLDER_KYC_REVIEW_PENDING, PROGRAM_CREATED, PROGRAM_PAUSED, PROGRAM_RESUMED, PROGRAM_CLOSED, PROGRAM_BALANCE_LOW, PROGRAM_BALANCE_FUNDED, PROGRAM_WITHDRAWAL_INITIATED, PROGRAM_WITHDRAWAL_COMPLETED, PROGRAM_WITHDRAWAL_FAILED, TRANSACTION_PROCESSED, TRANSACTION_AUTHORIZED, TRANSACTION_CLEARED, TRANSACTION_REVERSED, TRANSACTION_DECLINED, TRANSACTION_FEE, BILLING_INVOICE_CREATED, BILLING_INVOICE_PAID, BILLING_INVOICE_OVERDUE, BILLING_DEPOSIT_DETECTED, BILLING_DEPOSIT_CONFIRMED Example:
[
"CARD_ISSUED",
"CARD_FUNDED",
"TRANSACTION_AUTHORIZED",
"TRANSACTION_DECLINED"
]
Example:
"Production card events"
Response
Webhook created. The secret is at the top level alongside data — returned once only.
The secret field is a top-level sibling of data — not nested inside it. It is returned exactly once.
Example:
true
Example:
201
Example:
"Webhook created"
Show child attributes
Show child attributes
Raw signing secret — returned ONCE at creation time only. Store it securely.
Example:
"whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
Show child attributes
Show child attributes

