Gareth Wilson Gareth Wilson

Guide to HIFI Webhooks: Features and Best Practices

Published


HIFI provides APIs for moving money between bank accounts and stablecoins: onramps that turn a fiat deposit into stablecoins, offramps that pay stablecoins out to a bank, and the user onboarding, compliance and wallets around them. Almost every one of those operations finishes later than the API call that started it, after a bank transfer clears or a chain confirms. HIFI's v3 webhooks tell your platform when that happens.

We'll cover registering a HIFI endpoint through the API, the event naming scheme, checking hifi-signature, and the retry rule that switches off a subscription after ten failures.

What are HIFI webhooks?

HIFI webhooks are managed entirely through the API. You register an endpoint with a URL and a list of event types, and that endpoint receives only those types. A profile can have up to 16 endpoints, so you can split, for example, compliance events and money movement events across separate services.

Every delivery has the same envelope, and data always holds the resource's full current state, the same shape as a GET on that resource. That makes each event self-contained, but it also means a late, retried event can carry an older state than one you've already processed.

HIFI webhook features

FeatureDetails
Signaturehex HMAC-SHA256
Signature headerhifi-signature
BodyJSON
Event routingBody field eventType

From HIFI's webhooks overview:

  • Signature format: t=<unix seconds>,v1=<hex>, an HMAC of {t}.{raw_body}. HIFI recommends rejecting an old t.
  • Retries: any non-2xx, timeout or missing response is retried. The first retry comes after 30 seconds, and the delay doubles each time, with jitter, up to a 24-hour cap. There are at most 10 attempts.
  • After the final failure: the subscription for that event type on that endpoint is disabled.
  • Resend: an API call re-queues a single event to a single endpoint.

Events and payloads

Event types follow RESOURCE.EVENT for one-off events and RESOURCE.STATUS.<STATUS> for each value a resource's status can take. GET /webhook-endpoints/event-types returns the full list.

Some documented events are listed below; see the provider documentation for the full list.

EventMeaning
USER.CREATEDA user was created.
USER.STATUS.ACTIVEThe user is active.
USER.STATUS.INACTIVEThe user is inactive.
COMPLIANCE.CREATEDA compliance record was created for a user.
COMPLIANCE.STATUS.NOT_SUBMITTEDNo compliance information has been submitted yet.
COMPLIANCE.STATUS.PENDINGInformation submitted; queued for review.
COMPLIANCE.STATUS.IN_REVIEWActively under review.
COMPLIANCE.STATUS.APPROVEDCompliance cleared.

Other resources follow the same pattern: ONRAMP.* and OFFRAMP.* for conversions, WALLET.CREATED and WALLET.DEPOSIT for wallets, VIRTUAL_ACCOUNT.*, EXTERNAL_ACCOUNT.*, EXTERNAL_WALLET.*, and RFI.STATUS.* for compliance requests for information. When a resource has both a CREATED event and a CREATED status, creating it fires both RESOURCE.CREATED and RESOURCE.STATUS.CREATED. They are separate events, not duplicates.

HIFI's envelope example:

{
  "id": "evt_9f8e7d6c5b4a",
  "eventType": "ONRAMP.STATUS.COMPLETED",
  "eventCreatedAt": 1721856000000,
  "data": {
    "id": "onramp_QW1e2r3t4y",
    "status": "COMPLETED",
    "...": "full resource, same shape as the equivalent GET response"
  }
}

id identifies the event and is also what the resend API takes. eventCreatedAt is in milliseconds, while the signature's t is in seconds. HIFI's docs elide the rest of data, so check each resource's GET response in the API reference for its fields.

Setting up HIFI webhooks

Register an endpoint with an API key:

curl -X POST https://sandbox.hifi.com/v3/webhook-endpoints \
  -H "Idempotency-Key: <unique-key>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Production webhook",
    "url": "https://example.com/webhooks/hifi",
    "description": "Primary delivery endpoint",
    "subscriptions": ["ONRAMP.STATUS.COMPLETED", "OFFRAMP.STATUS.COMPLETED", "USER.STATUS.ACTIVE"]
  }'

The response includes the endpoint id and a signingSecret. HIFI returns the secret only in this response, never in a later GET, and there's no way to rotate it, so save it immediately, for example as HIFI_SIGNING_SECRET. To change subscriptions, PATCH the endpoint.

To route through Hookdeck, create a source with the HIFI type, register its URL as the endpoint url, and give the source the signingSecret as its verification secret. For local development:

npx hookdeck-cli listen 3000 hifi --path /webhooks/hifi

Then run an onramp or create a user in the sandbox to generate events.

Securing HIFI webhooks

Parse t and v1 from hifi-signature, build {t}.{raw_body}, compute a hex HMAC-SHA256 with the signing secret and compare it with v1 in constant time. HIFI's signature section also suggests rejecting a t that is too far in the past.

Node.js verification

const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['hifi-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const parts = signature.split(',').map((part) => part.trim());
  const times = parts.filter((part) => part.startsWith('t=')).map((part) => part.slice(2));
  if (times.length !== 1 || !/^[0-9]+$/.test(times[0])) return false;
  const message = Buffer.concat([Buffer.from(`${times[0]}.`, 'utf8'), rawBody]);
  const candidates = parts.filter((part) => part.startsWith('v1=')).map((part) => part.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

This verifier has no age check. If you add one, size it with HIFI's schedule in mind: retries can be up to 24 hours apart, so check whether a retry is re-signed with a new t before setting a short window.

HIFI suggests two ways to cope with out-of-order delivery. This handler takes the forward-only approach: it records the event, and applies the status only if it moves the resource forward.

const express = require('express');

const app = express();

app.post('/webhooks/hifi', express.raw({ type: '*/*' }), async (req, res) => {
  const signingSecret = process.env.HIFI_SIGNING_SECRET;
  if (!signingSecret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, signingSecret)) return res.sendStatus(401);

  let event;
  try {
    event = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }
  if (!event || typeof event !== 'object' || Array.isArray(event)) return res.sendStatus(400);
  try {
    const isNew = await recordHifiEvent(event.id, event.eventType, event.eventCreatedAt);
    if (isNew && event.data?.id) {
      await applyIfLaterStatus(event.data.id, event.eventType, event.data);
    }
  } catch {
    return res.sendStatus(503);
  }

  res.sendStatus(200);
});

applyIfLaterStatus compares the incoming status with the one you last stored for that resource and discards anything earlier in the lifecycle. The other option HIFI describes is to ignore data and call GET on the resource whenever an event arrives.

Hookdeck's HIFI source checks the same timestamped HMAC without an age limit. It answers HIFI with 200 straight away and records any signature mismatch as failed verification.

Make HIFI webhooks production-ready. Hookdeck Event Gateway verifies hifi-signature, accepts every HIFI delivery so your subscriptions stay enabled, and retries your service until onramp and compliance events are processed.

HIFI webhook limitations and pain points

Ten failures switch off a subscription

The Problem: After a long outage, an event type stops arriving even though your endpoint is healthy again.

Why It Happens: Once an event exhausts its 10 attempts, HIFI disables that event type's subscription on that endpoint. Nothing more is sent for it until you PATCH the endpoint with the subscription again.

Workarounds:

  • Alert on delivery failures well before the tenth attempt.
  • After any outage, check each endpoint's subscriptions and re-subscribe where needed, then use the resend API for events that failed.

How Hookdeck Can Help: Hookdeck acknowledges HIFI on every attempt, so subscriptions are never disabled because of your downtime, and Hookdeck's own retries deliver the backlog once your service returns.

Events arrive out of order

The Problem: A PENDING event can arrive after COMPLETED and roll a resource back if you apply it blindly.

Why It Happens: HIFI queues and retries each event independently, so a delayed retry can overtake a later change.

Workarounds:

  • Apply only forward status changes, and never move out of a terminal status.
  • Or treat the event as a prompt to GET the resource and use that response.

How Hookdeck Can Help: Hookdeck's event log shows the order in which deliveries arrived for each resource, which makes ordering problems easy to diagnose.

A secret you can't rotate

The Problem: A leaked or lost signing secret can't be replaced on the same endpoint.

Why It Happens: HIFI returns signingSecret once and has no rotate call. The documented fix is to delete the endpoint and register a new one.

Workarounds:

  • Register the replacement endpoint first, deploy its secret, then delete the old one. Deduplicate on event id while both are live.
  • Keep the secret in a secret manager from the moment it's returned.

How Hookdeck Can Help: If the endpoint points at a Hookdeck source, a new secret is configured on the source only, and the services behind it don't need redeploying.

Payload contents depend on the resource

The Problem: You can't see the full data for an event type from the webhook docs alone.

Why It Happens: HIFI's envelope example elides data and refers you to the matching GET response.

Workarounds:

  • Read the API reference for each resource you subscribe to.
  • Log a few sandbox deliveries before writing field mappings.

How Hookdeck Can Help: Hookdeck stores each sandbox delivery in full, so you can inspect real data objects for every event type.

Best practices

Subscribe per service

With up to 16 endpoints per profile, give each consuming service its own endpoint and subscription list. A failure in one then can't disable another's subscriptions.

Respond before you reconcile

Calling GET on the resource or updating balances belongs in a worker. Return 2xx once the event is stored, as recommended in asynchronous webhook processing.

Deduplicate on the event id

Retries and resends reuse the event id. Record it with the change it caused, as set out in the webhook idempotency guide.

Guard against status regressions

Keep a lifecycle order for each resource type and refuse to apply an earlier status than the one stored.

Conclusion

HIFI webhooks send the full state of an onramp, offramp, user or wallet whenever it changes, signed over a timestamp and the body in hifi-signature. Verify the raw body, deduplicate on event id, and apply only forward status changes, since events can arrive out of order. Above all, don't let an outage run to ten failed attempts, because HIFI then turns off that subscription.

Hookdeck Event Gateway keeps HIFI deliveries succeeding while your services catch up.

Get started with Hookdeck for free and handle HIFI webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.