Skip to main content
POST
Create a webhook

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

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

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.

Error Codes

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_TERMINATION_REFUND,
CARD_TERMINATION_REFUND_POST,
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:
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