upollo-webhooks

Upollo Webhooks

When to Use This Skill

• How do I receive Upollo webhooks?
• How do I verify the Upollo Upollo-Signature header?
• How do I verify an Upollo HMAC-SHA512 signature over the raw body?
• How do I react to an Upollo fraud flag like ACCOUNT_SHARING or MULTIPLE_ACCOUNTS?
• How do I handle the Upollo action (CHALLENGE / DENY / PERMIT / OFFER / LOG)?
• Why is my Upollo webhook signature verification failing?

How Upollo Webhooks Work

Upollo is a fraud / risk-detection platform. Unlike most providers, Upollo webhooks are not a subscription to discrete named events. A webhook fires whenever Upollo flags a user (for example account sharing or multi-accounting). Each delivery is an analysis describing the user, the device, the recommended action, and the list of flags that were raised.

Every delivery is signed. Upollo computes an HMAC-SHA512 of the raw request body, keyed with your webhook secret, and sends it in the Upollo-Signature header. Verify it against the raw body before doing anything else.

Not Standard Webhooks. Upollo does not use the Standard Webhooks (webhook-id / webhook-timestamp / webhook-signature) scheme. It uses a single Upollo-Signature header with t: and s0: parts (below).

Verification (core)

Upollo-Signature carries two comma-separated parts:

Upollo-Signature: t:1706352000,s0:3f9a...<128 hex chars>

• t — Unix timestamp of the delivery (seconds). Use it for optional replay protection; it is not part of the signed content.
• s0 — HMAC-SHA512(secret, rawBody). Recompute over the raw body and compare timing-safe.

Digest encoding. Upollo's docs don't state hex vs base64. The s0: prefix and observed 128-char values indicate lowercase hex. The snippets below compute the digest once and accept hex or base64 so they keep working either way — confirm hex against one live delivery, then you can drop base64.

Node:

const crypto = require('crypto');

function verifyUpolloWebhook(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;
  const s0 = Object.fromEntries(
    signatureHeader.split(',').map((p) => {
      const i = p.indexOf(':');
      return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
    })
  ).s0;
  if (!s0) return false;
  const digest = crypto.createHmac('sha512', secret).update(rawBody).digest();
  return [digest.toString('hex'), digest.toString('base64')].some((expected) => {
    try {
      return crypto.timingSafeEqual(Buffer.from(s0), Buffer.from(expected));
    } catch {
      return false; // length mismatch → not a match
    }
  });
}