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"
    ],
    "environment": "LIVE",
    "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"
  }
}

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.

​
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: Card events: CARD_ISSUED, CARD_FROZEN, CARD_UNFROZEN, CARD_TERMINATED, CARD_FUNDED, CARD_UNLOADED, CARD_FUND_FAILED, CARD_UNLOAD_FAILED Transaction events: TRANSACTION_AUTHORIZED, TRANSACTION_CLEARED, TRANSACTION_REVERSED, TRANSACTION_DECLINED, TRANSACTION_FEE Cardholder events: 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 events: PROGRAM_CREATED, PROGRAM_PAUSED, PROGRAM_RESUMED, PROGRAM_CLOSED, PROGRAM_BALANCE_LOW, PROGRAM_BALANCE_FUNDED, PROGRAM_WITHDRAWAL_INITIATED, PROGRAM_WITHDRAWAL_COMPLETED, PROGRAM_WITHDRAWAL_FAILED Billing events: BILLING_INVOICE_CREATED, BILLING_INVOICE_PAID, BILLING_INVOICE_OVERDUE, BILLING_DEPOSIT_DETECTED, BILLING_DEPOSIT_CONFIRMED

​
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",
    "environment":        "LIVE",
    "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