# Guide to HIFI Webhooks: Features and Best Practices

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

| Feature | Details |
| --- | --- |
| Signature | hex HMAC-SHA256 |
| Signature header | `hifi-signature` |
| Body | JSON |
| Event routing | Body field `eventType` |

From HIFI's [webhooks overview](https://docs.hifi.com/v3/core/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.

| Event | Meaning |
| --- | --- |
| `USER.CREATED` | A user was created. |
| `USER.STATUS.ACTIVE` | The user is active. |
| `USER.STATUS.INACTIVE` | The user is inactive. |
| `COMPLIANCE.CREATED` | A compliance record was created for a user. |
| `COMPLIANCE.STATUS.NOT_SUBMITTED` | No compliance information has been submitted yet. |
| `COMPLIANCE.STATUS.PENDING` | Information submitted; queued for review. |
| `COMPLIANCE.STATUS.IN_REVIEW` | Actively under review. |
| `COMPLIANCE.STATUS.APPROVED` | Compliance 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:

```json
{
  "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:

```bash
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:

```bash
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](https://docs.hifi.com/v3/core/webhooks/overview#verify-the-signature) also suggests rejecting a `t` that is too far in the past.

### Node.js verification

```javascript
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.

```javascript
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](/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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

### 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](/webhooks/guides/implement-webhook-idempotency).

### 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](https://hookdeck.com) keeps HIFI deliveries succeeding while your services catch up.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle HIFI webhooks reliably in minutes.