utila-webhooks

Utila Webhooks

Utila is a digital-asset operations platform. Webhooks notify your endpoint when transactions and wallets change state so you can reconcile them against the Utila API. Verification is asymmetric RSA, not HMAC — there is no shared secret.

When to Use This Skill

• How do I receive Utila webhooks?
• How do I verify the x-utila-signature header?
• Why is my Utila signature verification failing?
• How do I handle TRANSACTION_CREATED or TRANSACTION_STATE_UPDATED events?
• How do I configure a webhook in the Utila Console?

How Verification Works

Utila signs each delivery with an RSA-4096 private key using SHA-512 and PSS padding, base64-encodes the result, and sends it in the x-utila-signature header. You verify with Utila's PEM-encoded RSA-4096 public key, copied from the Console (Vault Settings → Webhooks). Key facts:

• No shared secret / no HMAC. You hold only the public key.
• Not Standard Webhooks. There is no webhook-id / webhook-timestamp header.
• No timestamp header, so Utila provides no built-in replay protection — dedupe on the event id and treat deliveries as idempotent.
• Always verify over the raw request body (exact bytes), before JSON parsing.

Verification (core)

const crypto = require('crypto');

// signatureB64: the raw x-utila-signature header value.
// rawBody:      the exact request bytes (Buffer), NOT parsed JSON.
// publicKeyPem: Utila's PEM RSA-4096 PUBLIC key from the Console.
function verifyUtilaSignature(rawBody, signatureB64, publicKeyPem) {
  if (!signatureB64) return false;
  try {
    return crypto.verify(
      'sha512',
      rawBody,
      {
        key: publicKeyPem,
        padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
        saltLength: crypto.constants.RSA_PSS_SALTLEN_AUTO, // auto-detect PSS salt
      },
      Buffer.from(signatureB64, 'base64')
    );
  } catch {
    return false; // malformed key/signature = not authentic
  }
}