Skip to main content
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"
}
'
{
  "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 HTTP 2xx 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

FieldTypeRequiredConstraintDescription
urlstringYeshttps:// required for LIVEYour endpoint URL
eventsarrayYes1–20 event typesList of event types to subscribe to
descriptionstringNoMax 255 charsInternal 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"
    ]
  }'

​
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

CodeHTTPCause
WEBHOOK_LIMIT_REACHED422Maximum of 10 webhook endpoints per environment
WEBHOOK_HTTPS_REQUIRED422LIVE environment requires an https:// URL
INVALID_EVENT_TYPE422One or more event types in events are not recognised
VALIDATION_ERROR422Missing or invalid fields
INSUFFICIENT_SCOPE403Key lacks webhooks:write scope

Authorizations

​
Authorization
string
header
required

API key from the FYATU CaaS portal. Pass as Authorization: Bearer <key>.

Body

application/json
​
url
string<uri>
required
Example:

"https://yourapp.com/webhooks/fyatu"

​
events
enum<string>[]
required
Required array length: 1 - 20 elements
Available options:
CARD_ISSUED,
CARD_FROZEN,
CARD_UNFROZEN,
CARD_TERMINATED,
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_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"
]
​
description
string
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.

​
success
boolean
Example:

true

​
status
integer
Example:

201

​
message
string
Example:

"Webhook created"

​
data
object
​
secret
string

Raw signing secret — returned ONCE at creation time only. Store it securely.

Example:

"whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"

​
meta
object