Webhooks

Catálogo de eventos

Pregunte a API a qué eventos puede suscribirse. El catálogo se deriva de la fuente de información en tiempo real de los activadores de automatización, por lo que solo incluye los eventos que se activan hoy, agrupados por etapa del ciclo de vida (adquisición, participación, fidelización, retención, comercio, promoción), cada uno con su clave de evento, una descripción y un ejemplo de carga útil. La respuesta también documenta el sobre de carga útil compartida y los encabezados de firma.

curl https://flash.socialhub.ai/api/v2/events/catalog \
  -H "Authorization: Bearer fl_live_..."

# { "data": { "events": [
#     { "event": "member.created", "label": "Member created",
#       "stage": "acquisition", "examplePayload": { ... } },
#     { "event": "loyalty.tier_upgraded", "label": "Tier upgraded",
#       "stage": "loyalty", "examplePayload": { ... } },
#     ...
#   ],
#   "payload": { "schema": { ... }, "headers": { ... } }
# } }

Introduce la clave event de un evento directamente en eventTypes array al suscribirte. Requiere el alcance webhooks:manage.

Verificar cada firma

Flash firma cada entrega con el secreto whsec_ de su punto final usando Webhooks estándar (HMAC-SHA256). Recalcula la firma sobre {webhook-id}.{webhook-timestamp}.{body} y compárala, en tiempo constante, con el encabezado webhook-signature. Rechaza todo lo que no coincida y rechaza un webhook-timestamp que sea demasiado antiguo para protegerse contra repeticiones. La clave de firma son los bytes decodificados en base64 del secreto después del prefijo whsec_, según la especificación. Durante una rotación de secreto, el encabezado lleva múltiples valores v1,… separados por espacios; acepta la entrega si alguno coincide.

import crypto from "node:crypto";

// req.body must be the RAW, unparsed request body string.
function verifyFlashWebhook(headers, rawBody, whsec) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  const sigHeader = headers["webhook-signature"]; // "v1,<b64> v1,<b64> ..."

  // reject stale deliveries (5 min tolerance)
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const key = Buffer.from(whsec.replace(/^whsec_/, ""), "base64");
  const expected = crypto
    .createHmac("sha256", key)
    .update(`${id}.${ts}.${rawBody}`)
    .digest("base64");

  return sigHeader
    .split(" ")
    .map((p) => p.split(",")[1])
    .some((sig) =>
      sig &&
      sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)),
    );
}