Webhook Signature Verification

Every webhook delivery from FYATU includes an X-Fyatu-Signature header. Verify this signature before processing any event — it proves the request originated from FYATU and the body has not been tampered with.

X-Fyatu-Signature: t=1716372000,v1=3a5b8c2d1e4f9a0b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b

Delivery Headers

Every webhook delivery includes these headers:

Header	Example	Description
`X-Fyatu-Signature`	`t=1716372000,v1=abc123...`	Unix timestamp + HMAC-SHA256 signature
`X-Fyatu-Timestamp`	`1716372000`	Unix timestamp (same as `t=` in signature)
`X-Fyatu-Event`	`CARD_ISSUED`	Event type in UPPERCASE_SNAKE format
`X-Fyatu-Event-ID`	`evt_01HXY123456ABCDEF`	Unique event ID — use for deduplication
`X-Fyatu-Environment`	`LIVE`	`LIVE` or `SANDBOX`
`User-Agent`	`Fyatu-Webhook/3.20`	Sender identification

Event names use UPPERCASE_SNAKE format: CARD_ISSUED, TRANSACTION_PROCESSED, CARDHOLDER_KYC_APPROVED. Earlier docs may reference dot-notation names such as card.issued — those are deprecated. Always use the header value as the canonical event name.

Webhook Payload Envelope

All events share the same outer envelope:

{
  "event":       "CARD_ISSUED",
  "eventId":     "evt_01HXY123456ABCDEF",
  "businessId":  "BUS1A2B3C4D5E6F",
  "environment": "LIVE",
  "timestamp":   "2026-05-22T10:00:00Z",
  "data": {
    "cardId":    "crd_01HXYZ5555ABCDEF1111",
    "status":    "ACTIVE",
    "programId": "prg_01HXYZ9876ABCDEF0000"
  }
}

Field	Description
`event`	Event type — matches `X-Fyatu-Event` header
`eventId`	Unique event ID — matches `X-Fyatu-Event-ID` header
`businessId`	Your business identifier
`environment`	`LIVE` or `SANDBOX`
`timestamp`	ISO 8601 event timestamp
`data`	Event-specific payload — varies by event type

The Signing Algorithm

FYATU signs every webhook using a two-step process. Step 1 — Derive the signing key Your raw webhook secret (whsec_...) is never used directly as the HMAC key. Instead, FYATU computes:

signingKey = hex( SHA-256( rawSecret ) )

Step 2 — Sign the message The signed message is {timestamp}.{fullRequestBody}:

signature = hex( HMAC-SHA256( signingKey, "{timestamp}.{body}" ) )

Where timestamp is the Unix timestamp from the t= field in X-Fyatu-Signature, and body is the raw request body bytes before any JSON parsing. Step 3 — Compare Extract v1 from the header and compare with your computed signature using a constant-time comparison function to prevent timing attacks.

Verification Examples

const crypto  = require('crypto');
const express = require('express');
const app     = express();

// Must be set BEFORE express.json() to capture raw bytes
app.use('/webhooks/fyatu', express.raw({ type: 'application/json' }));

function verifyFyatuSignature(rawBody, signatureHeader, rawSecret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('='))
  );
  const timestamp = parts['t'];
  const v1        = parts['v1'];

  if (!timestamp || !v1) return false;

  // Derive signing key: hex(SHA-256(rawSecret))
  const signingKey = crypto.createHash('sha256')
    .update(rawSecret, 'utf8')
    .digest('hex');

  // Sign: HMAC-SHA256(signingKey, "{timestamp}.{body}")
  const message  = `${timestamp}.${rawBody}`;
  const expected = crypto.createHmac('sha256', signingKey)
    .update(message, 'utf8')
    .digest('hex');

  // Constant-time compare
  return crypto.timingSafeEqual(
    Buffer.from(v1, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

app.post('/webhooks/fyatu', (req, res) => {
  const sigHeader = req.headers['x-fyatu-signature'];
  const rawSecret = process.env.FYATU_WEBHOOK_SECRET;

  if (!sigHeader) return res.status(400).json({ error: 'Missing signature' });

  if (!verifyFyatuSignature(req.body, sigHeader, rawSecret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const payload   = JSON.parse(req.body);
  const eventId   = req.headers['x-fyatu-event-id'];
  const eventType = payload.event;

  switch (eventType) {
    case 'TRANSACTION_PROCESSED':
      // show pending transaction in cardholder's history
      break;
    case 'CARDHOLDER_KYC_APPROVED':
      // unlock card issuance for this cardholder
      break;
    case 'CARD_ISSUED':
      // mark card as ready in your system
      break;
  }

  res.status(200).json({ received: true });
});

import hashlib, hmac, os
from flask import Flask, request, jsonify, abort

app = Flask(__name__)

def verify_fyatu_signature(raw_body: bytes, sig_header: str, raw_secret: str) -> bool:
    parts     = dict(p.split('=', 1) for p in sig_header.split(','))
    timestamp = parts.get('t')
    v1        = parts.get('v1')

    if not timestamp or not v1:
        return False

    # Derive signing key: hex(SHA-256(rawSecret))
    signing_key = hashlib.sha256(raw_secret.encode('utf-8')).hexdigest()

    # Sign: HMAC-SHA256(signingKey, "{timestamp}.{body}")
    message  = f'{timestamp}.{raw_body.decode("utf-8")}'.encode('utf-8')
    expected = hmac.new(
        signing_key.encode('utf-8'),
        message,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, v1)

@app.route('/webhooks/fyatu', methods=['POST'])
def handle_webhook():
    sig_header = request.headers.get('X-Fyatu-Signature', '')
    raw_secret = os.environ['FYATU_WEBHOOK_SECRET']

    if not verify_fyatu_signature(request.get_data(), sig_header, raw_secret):
        abort(401)

    payload    = request.get_json()
    event_type = payload['event']
    event_id   = request.headers.get('X-Fyatu-Event-ID')

    if event_type == 'TRANSACTION_PROCESSED':
        pass  # handle authorization
    elif event_type == 'CARDHOLDER_KYC_APPROVED':
        pass  # unlock card issuance

    return jsonify({'received': True}), 200

<?php

function verifyFyatuSignature(string $rawBody, string $sigHeader, string $rawSecret): bool
{
    $parts = [];
    foreach (explode(',', $sigHeader) as $part) {
        [$k, $v] = explode('=', $part, 2);
        $parts[$k] = $v;
    }
    if (empty($parts['t']) || empty($parts['v1'])) {
        return false;
    }

    // Derive signing key: hex(SHA-256(rawSecret))
    $signingKey = hash('sha256', $rawSecret);

    // Sign: HMAC-SHA256(signingKey, "{timestamp}.{body}")
    $message  = $parts['t'] . '.' . $rawBody;
    $expected = hash_hmac('sha256', $message, $signingKey);

    return hash_equals($expected, $parts['v1']);
}

$rawBody   = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_X_FYATU_SIGNATURE'] ?? '';
$rawSecret = getenv('FYATU_WEBHOOK_SECRET');

if (!verifyFyatuSignature($rawBody, $sigHeader, $rawSecret)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

$payload   = json_decode($rawBody, true);
$eventType = $payload['event'];
$eventId   = $_SERVER['HTTP_X_FYATU_EVENT_ID'] ?? '';

switch ($eventType) {
    case 'TRANSACTION_PROCESSED':
        // handle authorization
        break;
    case 'CARDHOLDER_KYC_APPROVED':
        // unlock card issuance
        break;
}

http_response_code(200);
echo json_encode(['received' => true]);

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
)

func verifyFyatuSignature(rawBody []byte, sigHeader, rawSecret string) bool {
    parts := map[string]string{}
    for _, p := range strings.Split(sigHeader, ",") {
        kv := strings.SplitN(p, "=", 2)
        if len(kv) == 2 {
            parts[kv[0]] = kv[1]
        }
    }
    timestamp, v1 := parts["t"], parts["v1"]
    if timestamp == "" || v1 == "" {
        return false
    }

    // Derive signing key: hex(SHA-256(rawSecret))
    h          := sha256.Sum256([]byte(rawSecret))
    signingKey := hex.EncodeToString(h[:])

    // Sign: HMAC-SHA256(signingKey, "{timestamp}.{body}")
    message := fmt.Sprintf("%s.%s", timestamp, rawBody)
    mac     := hmac.New(sha256.New, []byte(signingKey))
    mac.Write([]byte(message))
    expected := hex.EncodeToString(mac.Sum(nil))

    expectedBytes, err1 := hex.DecodeString(expected)
    v1Bytes, err2       := hex.DecodeString(v1)
    if err1 != nil || err2 != nil {
        return false
    }
    return hmac.Equal(v1Bytes, expectedBytes)
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    rawBody, _ := io.ReadAll(r.Body)
    sigHeader  := r.Header.Get("X-Fyatu-Signature")
    rawSecret  := os.Getenv("FYATU_WEBHOOK_SECRET")

    if !verifyFyatuSignature(rawBody, sigHeader, rawSecret) {
        http.Error(w, `{"error":"Invalid signature"}`, http.StatusUnauthorized)
        return
    }

    eventType := r.Header.Get("X-Fyatu-Event")
    switch eventType {
    case "TRANSACTION_PROCESSED":
        // handle authorization
    case "CARDHOLDER_KYC_APPROVED":
        // unlock card issuance
    }

    w.Header().Set("Content-Type", "application/json")
    w.Write([]byte(`{"received":true}`))
}

func main() {
    http.HandleFunc("/webhooks/fyatu", webhookHandler)
    http.ListenAndServe(":8080", nil)
}

require 'sinatra'
require 'openssl'
require 'json'

def verify_fyatu_signature(raw_body, sig_header, raw_secret)
  parts     = sig_header.split(',').map { |p| p.split('=', 2) }.to_h
  timestamp = parts['t']
  v1        = parts['v1']
  return false if timestamp.nil? || v1.nil?

  # Derive signing key: hex(SHA-256(rawSecret))
  signing_key = OpenSSL::Digest::SHA256.hexdigest(raw_secret)

  # Sign: HMAC-SHA256(signingKey, "{timestamp}.{body}")
  message  = "#{timestamp}.#{raw_body}"
  expected = OpenSSL::HMAC.hexdigest('sha256', signing_key, message)

  Rack::Utils.secure_compare(expected, v1)
end

post '/webhooks/fyatu' do
  raw_body   = request.body.read
  sig_header = request.env['HTTP_X_FYATU_SIGNATURE'] || ''
  raw_secret = ENV['FYATU_WEBHOOK_SECRET']

  halt 401, { error: 'Invalid signature' }.to_json \
    unless verify_fyatu_signature(raw_body, sig_header, raw_secret)

  payload    = JSON.parse(raw_body)
  event_type = payload['event']

  case event_type
  when 'TRANSACTION_PROCESSED' then # handle it
  when 'CARDHOLDER_KYC_APPROVED' then # handle it
  end

  content_type :json
  { received: true }.to_json
end

Replay Attack Prevention

The t= timestamp in the signature header lets you reject stale requests. Reject any delivery where the timestamp is more than 5 minutes old:

const MAX_AGE_SECONDS = 5 * 60; // 5 minutes

function isFresh(sigHeader) {
  const parts = Object.fromEntries(
    sigHeader.split(',').map(p => p.split('='))
  );
  const ts = parseInt(parts['t'], 10);
  return Math.abs(Date.now() / 1000 - ts) <= MAX_AGE_SECONDS;
}

Always enforce the 5-minute window. Without it, an attacker who captures a delivery can replay it hours or days later.

Idempotency — Deduplicating Retries

FYATU retries failed deliveries up to 5 times. The same event may arrive more than once. Use X-Fyatu-Event-ID (also available as eventId in the body) to deduplicate:

const eventId = req.headers['x-fyatu-event-id'];

// Check if already processed
if (await db.processedEvents.exists(eventId)) {
  return res.status(200).json({ received: true }); // idempotent — already handled
}

// Mark as processing before doing work (prevent race conditions)
await db.processedEvents.insert(eventId);

// ... process the event ...

Retry Schedule

FYATU retries failed deliveries (any response other than 2xx) on this schedule:

Attempt	Delay after previous failure
1st retry	~5 minutes
2nd retry	~30 minutes
3rd retry	~2 hours
4th retry	~8 hours
5th retry	~24 hours

After 5 failed attempts the delivery is marked FAILED permanently. You can view and manually replay failed deliveries from the portal under Developer → Webhooks.

Respond 200 OK within 30 seconds — process events asynchronously using a queue. Long-running handlers that time out are treated as failures and trigger a retry.

Best Practices

Use raw body

Always capture the raw request body bytes before JSON parsing. Re-serializing parsed JSON can change whitespace or key order, breaking the signature.

Respond quickly

Return 200 within 30 seconds. Queue events for async processing if your handler does database writes or external API calls.

Reject stale timestamps

Enforce a 5-minute window on t= to prevent replay attacks where captured requests are redelivered later.

Deduplicate with Event-ID

Store processed X-Fyatu-Event-ID values. A retry arriving after your handler already ran should return 200 immediately without re-processing.

Rotate secrets safely

If your webhook secret is compromised, delete the webhook endpoint and create a new one. The old secret stops working immediately.

Test with SANDBOX first

Use the portal’s Send Test Event feature to fire a sample payload to your endpoint before going live.

Guides

JIT Authorization

Card Events

Transaction Events

Cardholder Events

Account Events

Billing Events

Signature Verification

Webhook Signature Verification

Delivery Headers

Webhook Payload Envelope

The Signing Algorithm

Verification Examples

Replay Attack Prevention

Idempotency — Deduplicating Retries

Retry Schedule

Best Practices

Use raw body

Respond quickly

Reject stale timestamps

Deduplicate with Event-ID

Rotate secrets safely

Test with SANDBOX first

​Webhook Signature Verification

​Delivery Headers

​Webhook Payload Envelope

​The Signing Algorithm

​Verification Examples

​Replay Attack Prevention

​Idempotency — Deduplicating Retries

​Retry Schedule

​Best Practices

Use raw body

Respond quickly

Reject stale timestamps

Deduplicate with Event-ID

Rotate secrets safely

Test with SANDBOX first

Webhook Signature Verification

Delivery Headers

Webhook Payload Envelope

The Signing Algorithm

Verification Examples

Replay Attack Prevention

Idempotency — Deduplicating Retries

Retry Schedule

Best Practices