HIFI Docs

How Webhooks Work

Configure a webhook endpoint URL in the HIFI Dashboard.

Receive events

HIFI sends POST requests to your endpoint when events occur.

Verify signature

Validate the JWT signature using your webhook secret to ensure authenticity.

Process event

Execute your application logic based on the event data.

Return 2xx response

Respond with a 2xx status code to acknowledge receipt.

Registering Webhooks

Navigate to Developer → Webhooks
Enter your webhook URL (must be HTTPS)
Save to receive your webhook secret

Webhook Secret: After registration, you’ll receive a public key used to verify webhook signatures. Store this securely - you’ll need it to validate incoming requests.

Event Structure

All webhook events follow a consistent structure:

{
  "eventId": "evt_1957117404034e3ade",
  "eventCategory": "USER",
  "eventType": "USER.CREATE",
  "eventAction": "CREATE",
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "type": "individual",
    "wallets": {
      "INDIVIDUAL": {
        "POLYGON": {
          "address": "0xa8A642FBA80749318036C97344fC73aE0B64c608"
        }
      }
    }
  },
  "createdAt": "2025-03-07T14:51:44.099Z",
  "timestamp": "2025-03-07T14:52:00.375Z",
  "version": "v2"
}

Event Fields:

string

Unique identifier for this webhook event.

string

Broad category describing the domain of the event (e.g., USER, WALLET, ONRAMP, OFFRAMP).

string

Specific event type or trigger (such as USER.CREATE, WALLET.TRANSFER.UPDATE).

string

Operation performed (CREATE, UPDATE, DELETE).

object

Object containing details and payload for this event (structure varies by event type).

string

ISO timestamp when the event was generated by HIFI.

string

ISO timestamp when the webhook was delivered.

string

Version of the webhook/event payload schema (e.g., v2).

Event Types

HIFI sends webhook events for various types of operations. Each event category has a dedicated page with detailed information about the event types, payloads, and examples.

User Events - Events for user creation and updates
KYC Events - Events for KYC data and status changes
Wallet Events - Events for wallet transfers, bridges, and token balance updates
Account Events - Events for onramp, offramp, and virtual account creation and updates
Onramp Events - Events for onramp transfer creation and status updates
Offramp Events - Events for offramp transfer creation and status updates

Verifying Webhook Signatures

Critical: Always verify webhook signatures to ensure requests are from HIFI and haven’t been tampered with.

Verification Process

Webhooks include a JWT token in the Authorization header. Verify this token using your webhook public key:

Extract the JWT token from the Authorization: Bearer <token> header
Verify the token using your webhook public key with RS256 algorithm
If verification succeeds, process the event
If verification fails, reject the request with 401 status

Implementation Examples

from flask import Flask, request, jsonify
import jwt

app = Flask(**name**)
webhook_public_key = '''-----BEGIN PUBLIC KEY-----
your_webhook_public_key_here
-----END PUBLIC KEY-----'''

@app.route('/webhook', methods=['POST'])
def webhook():
auth_header = request.headers.get('Authorization')
if not auth_header:
return 'Authorization header is missing', 401

    jwt_token = auth_header.split(' ')[1]

    try:
        decoded = jwt.decode(jwt_token, webhook_public_key, algorithms=['RS256'])
        print('Token is valid. Decoded payload:', decoded)

        # Process the event
        event_type = decoded.get('eventType')
        event_data = decoded.get('data')

        # Your application logic here
        handle_event(event_type, event_data)

        return '', 200
    except jwt.ExpiredSignatureError:
        print('Token has expired')
        return 'Token has expired', 401
    except jwt.InvalidTokenError as e:
        print('Failed to verify token:', str(e))
        return 'Token verification failed', 401

def handle_event(event_type, data):
if event_type == 'WALLET.TRANSFER.UPDATE': # Update transaction status in your database
pass
elif event_type == 'USER.KYC.UPDATE': # Notify user of KYC status change
pass

if **name** == '**main**':
app.run(port=3000)

const express = require("express");
const jwt = require("jsonwebtoken");

const app = express();
const webhookPublicKey = `-----BEGIN PUBLIC KEY-----
your_webhook_public_key_here
-----END PUBLIC KEY-----`;

app.use(express.json());

app.post("/webhook", (req, res) => {
  const authHeader = req.headers.authorization;
  if (!authHeader) {
    return res.status(401).send("Authorization header is missing");
  }

  const jwtToken = authHeader.split(" ")[1];

  try {
    const decoded = jwt.verify(jwtToken, webhookPublicKey, {
      algorithms: ["RS256"],
    });
    console.log("Token is valid. Decoded payload:", decoded);

    // Process the event
    const { eventType, data } = decoded;

    // Your application logic here
    handleEvent(eventType, data);

    res.status(200).send("");
  } catch (error) {
    if (error.name === "TokenExpiredError") {
      console.log("Token has expired");
      return res.status(401).send("Token has expired");
    } else {
      console.log("Failed to verify token:", error.message);
      return res.status(401).send("Token verification failed");
    }
  }
});

function handleEvent(eventType, data) {
  if (eventType === 'WALLET.TRANSFER.UPDATE') {
    // Update transaction status in your database
  } else if (eventType === 'USER.KYC.UPDATE') {
    // Notify user of KYC status change
  }
}

app.listen(3000, () => {
  console.log("Webhook server running on port 3000");
});

Retry Behavior

HIFI automatically retries failed webhook deliveries to ensure reliability.

Retry Schedule

Duration: Up to 24 hours
Strategy: Exponential backoff
Interval: 60 seconds to 1 hour between retries
Success criteria: Your endpoint returns a 2xx status code

Retry Conditions

HIFI retries when:

Your endpoint returns a 5xx error
Connection timeout occurs
Network error prevents delivery

HIFI does not retry when:

Your endpoint returns a 4xx error (indicates a permanent failure)
Your webhook endpoint is disabled or deleted
24 hours have elapsed since the original event

Endpoint availability matters: If your endpoint is disabled when HIFI attempts a retry, future retries for that event are prevented. Re-enable your endpoint before the next retry attempt to continue receiving retries.

Best Practices

Respond quickly

Return a 2xx response as soon as you receive the webhook, before processing the event. Process the event asynchronously to avoid timeouts:

app.post('/webhook', (req, res) => {
  // Verify signature
  const event = verifyAndExtract(req);
  
  // Respond immediately
  res.status(200).send('');
  
  // Process asynchronously
  processEventAsync(event);
});

Implement idempotency

Use eventId to ensure you process each event only once. Store processed event IDs:

async function handleEvent(event) {
  // Check if already processed
  const processed = await db.hasProcessed(event.eventId);
  if (processed) {
    console.log('Event already processed:', event.eventId);
    return;
  }
  
  // Process event
  await processEvent(event);
  
  // Mark as processed
  await db.markProcessed(event.eventId);
}

Handle event order

Events may arrive out of order. Use createdAt and timestamp to determine the correct sequence. Store the latest known state:

function shouldProcessEvent(event, currentState) {
  const eventTime = new Date(event.createdAt);
  const lastUpdate = new Date(currentState.lastUpdatedAt);
  
  // Only process if this event is newer
  return eventTime > lastUpdate;
}

Monitor webhook health

Track webhook delivery success rates and response times. Set up alerts for: - High failure rates - Slow response times - Signature verification failures This helps identify issues early before retries are exhausted.

Test with sandbox

Use the HIFI sandbox environment to test your webhook integration:

Register a test webhook endpoint
Trigger test events using sandbox API
Verify your endpoint handles events correctly
Test retry behavior by temporarily failing your endpoint

Getting Help

📧 Email: support@hifi.com
💬 Slack: Message us in our shared Slack channel

Wallet Transfers - Track transfer events
Onramps - Monitor onramp events
Offramps - Track offramp events
Users - Monitor user and KYC events

Introduction

Core concepts

Features

Compliance

Payments

References

Events & Webhooks

How Webhooks Work

Registering Webhooks

Event Structure

Event Types

Verifying Webhook Signatures

Verification Process

Implementation Examples

Retry Behavior

Retry Schedule

Retry Conditions

Best Practices

Getting Help

​How Webhooks Work

​Registering Webhooks

​Event Structure

​Event Types

​Verifying Webhook Signatures

​Verification Process

​Implementation Examples

​Retry Behavior

​Retry Schedule

​Retry Conditions

​Best Practices

​Getting Help

​Related Resources

How Webhooks Work

Registering Webhooks

Event Structure

Event Types

Verifying Webhook Signatures

Verification Process

Implementation Examples

Retry Behavior

Retry Schedule

Retry Conditions

Best Practices

Getting Help

Related Resources