Fordefi Webhook Handler (TypeScript)

A TypeScript Express.js webhook server that listens for events from your Fordefi organization and processes transaction data.

Prerequisites

• Node.js 18+
• npm or yarn
• Fordefi API User Token - Get your token here
• Fordefi Public Key - Download from webhook docs

Installation

1. Clone and navigate

   cd api-examples/typescript/webhooks

2. Install dependencies

   npm install express axios dotenv
   npm install -D typescript @types/express @types/node ts-node nodemon

3. Initialize TypeScript config

   npx tsc --init

Configuration

1. Environment Variables
   Create a .env file:

   FORDEFI_API_USER_TOKEN=your_fordefi_api_token_here
   PORT=8080

2. Public Key Setup
   Download the Fordefi public key and save it as public_key.pem in the same directory:

   # Download from: https://docs.fordefi.com/developers/webhooks#validate-a-webhook
   # Save as: public_key.pem

3. Package.json Scripts
   Add these scripts to your package.json:

   {
     "scripts": {
       "dev": "nodemon --exec ts-node app.ts",
       "build": "tsc",
       "start": "node dist/app.js"
     }
   }

Usage

Development Mode (with auto-reload)

npm run dev

Production Mode

npm run build
npm start

Direct Execution

npx ts-node app.ts

API Endpoints

Method	Endpoint	Description
POST	/	Main webhook endpoint for Fordefi events

Webhook Request Flow

1. Signature Verification - Validates X-Signature header using ECDSA P-256
2. Event Processing - Parses webhook payload and extracts transaction ID
3. Data Fetching - Retrieves full transaction data from Fordefi API
4. Response - Returns transaction data or success message

Example Response

{
  "id": "transaction_id_here",
  "status": "completed",
  "blockchain": "ethereum",
  "type": "transfer",
  // ... additional transaction data
}

Testing with ngrok

1. Install ngrok

   # Install ngrok: https://ngrok.com/download

2. Start your webhook server

   npm run dev

3. Expose locally with ngrok

   ngrok http 8080

4. Configure Fordefi Webhook

   • Go to Fordefi Console → Settings → Webhooks
   • Add webhook URL: https://your-ngrok-url.ngrok.io/
   • Save and test

Project Structure

webhooks/
├── app.ts              # Main application file
├── package.json        # Dependencies and scripts
├── tsconfig.json       # TypeScript configuration
├── .env               # Environment variables
├── public_key.pem     # Fordefi public key
└── README.md          # This file

Environment Variables

Variable	Required	Description
FORDEFI_API_USER_TOKEN	Yes	Your Fordefi API access token
PORT	No	Server port (default: 8080)

Learn More

📚 Documentation Links:

• Fordefi Webhook Guide
• Fordefi API Reference
• Signature Validation