Agent skill

HIFI Webhooks Skill

Receive and verify HIFI webhooks. Use when configuring HIFI webhook endpoints, debugging hifi-signature signatures, or handling ONRAMP.STATUS.COMPLETED, USER.CREATED, CRYPTO_TRANSFER.CREATED.

Install this skill

npx skills add hookdeck/webhook-skills --skill hifi-webhooks


Receive HIFI user, compliance and money-movement events.

When to Use This Skill

  • Configure a receiver for HIFI webhook deliveries.
  • Diagnose hifi-signature verification failures.
  • Handle ONRAMP.STATUS.COMPLETED, USER.CREATED, CRYPTO_TRANSFER.CREATED.

Setup

Register an endpoint with the HIFI Webhooks API, set its subscriptions, and store the signingSecret returned at registration. It is shown only once. To replace the secret, delete and register the endpoint again.

Set HIFI_WEBHOOK_SECRET in the server environment. Read setup before enabling delivery.

Verification (core)

hifi-signature contains t=<Unix seconds>,v1=<hex> over timestamp + "." + raw body. Use HMAC-SHA256 with the secret's UTF-8 bytes. Verify the original bytes before parsing JSON. Validate the digest format, then compare equal-length buffers in constant time.

After extracting the documented digest and constructing message as described in verification, the comparison is:

const expected = crypto.createHmac('sha256', secret).update(message).digest();
if (digest.length !== 64 || !/^[0-9a-fA-F]{64}$/.test(digest)) return false;
const received = Buffer.from(digest, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);

Set HIFI_WEBHOOK_TOLERANCE_SECONDS to a positive number to enforce an application age limit in seconds. Unset or 0 disables it. Old timestamps remain valid by default so Hookdeck retries and replays can retain the original headers.

Complete handlers and tests: Express, Next.js, FastAPI.

Event Handling

The envelope contains id, eventType, eventCreatedAt and data. Use eventType for dispatch; data is the resource state. RESOURCE.CREATED and RESOURCE.STATUS.CREATED are distinct notifications.

Return 2xx promptly. HIFI retries failed deliveries with exponential backoff for up to 10 attempts. Deliveries may arrive out of order; reconcile the resource state before applying a change.

Local Development

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

Use port 8000 for FastAPI. The CLI provides a local tunnel and inspection UI; no account is required to start.

Resources

Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →