Rotar Signing Secret

Visión general

Ayrshare firma cada entrega de webhook con un HMAC-SHA256 del payload, usando como clave tu signing secret, para que tu receptor pueda confirmar que la entrega procede realmente de Ayrshare. Consulta Seguridad de webhook para ver cómo funciona la verificación. Rotar tu signing secret te permite reemplazarlo de forma regular, o inmediatamente si sospechas que ha quedado expuesto. Para que la rotación sea segura, Ayrshare abre una ventana de gracia de 24 horas después de cada rotación durante la cual las entregas se firman con ambos secrets, el anterior y el nuevo. Esto te permite actualizar tu receptor a tu propio ritmo sin descartar ni rechazar una sola entrega — el mismo patrón que usan Stripe y GitHub.

El signing secret es a nivel de perfil: hay un secret por User Profile (UID), y firma todas las acciones de webhook que ese perfil tenga registradas. No existe un signing secret por acción — establecer o rotar el secret lo cambia para todas las acciones de ese perfil a la vez.

Rotar desde el Dashboard

Puedes establecer o rotar tu signing secret desde la página Webhooks del Developer Dashboard. El panel Signing Secret aparece encima de tu lista de webhooks una vez que el perfil tiene al menos un webhook registrado.

Abre el panel Signing Secret

Ve a la página Webhooks. Si aún no hay ningún secret configurado, el panel muestra No signing secret configured con un botón Set Signing Secret. Si ya hay uno configurado, muestra Signing secret configured con un botón Rotate.

Set o Rotate

Haz clic en Set Signing Secret (por primera vez) o en Rotate (secret existente). Se abre un modal con un secret fuerte generado aleatoriamente ya rellenado y visible. Puedes hacer Copy, Regenerate para generar uno nuevo, o activar paste my own para introducir tu propio valor.

Confirma

Copia el secret en un lugar seguro — se muestra solo una vez y nunca podrá recuperarse desde la UI — y confirma para enviarlo. Aparece un toast de éxito y el panel se actualiza.

Actualiza tu receptor

En una rotación (no en una configuración inicial), el panel muestra un indicador de ventana de gracia activa y el botón Rotate queda deshabilitado hasta que la ventana se cierre. Tienes 24 horas para desplegar el nuevo secret en tu receptor.

Rotar mediante la API

Rota (o establece) el signing secret con una única llamada. Esto crea un nuevo secret, reapunta la referencia del secret del perfil a él y — cuando ya existía un secret — registra el secret sustituido como el secret anterior con una expiración a 24 horas vista.

Parámetros de cabecera

Parámetros del cuerpo

string

requerido

El nuevo valor del signing secret. Se acepta cualquier string no vacío. Recomendamos un valor aleatorio largo y de alta entropía (por ejemplo, 32 bytes aleatorios codificados en base64url).

curl --request POST \
  --url https://api.ayrshare.com/api/hook/webhook/secret \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Profile-Key: YOUR_PROFILE_KEY' \
  --data '{
    "secret": "your-new-signing-secret"
  }'

{
  "status": "success",
  "action": "webhook",
  "refId": "3dc079614bdc3f281d9" // User Profile Ref Id
}

El secret en texto plano nunca se devuelve en la respuesta y nunca se registra en logs. La respuesta contiene el refId orientado al cliente (un hash del UID), nunca el UID en sí. La cabecera Profile-Key es opcional y limita la rotación a un único User Profile para cuentas multiperfil. Un secret faltante o vacío devuelve un error mapeado (code: 101, “Missing/incorrect parameter”) con un status HTTP 400, y no se realiza ningún cambio en tu secret actual. La configuración inicial mediante la API (sin secret existente) crea el secret sin registrar un secret anterior y sin ventana de gracia.

Procedimiento seguro de rotación

Gracias a la ventana de gracia de 24 horas, no hay un orden de operaciones obligatorio — tu receptor sigue funcionando durante todo el proceso. La secuencia recomendada es:

Rota el secret

Rota desde el dashboard o mediante la API. Ayrshare comienza inmediatamente a firmar las entregas con ambos secrets, el anterior y el nuevo.

Actualiza tu receptor

En un plazo de 24 horas, despliega el nuevo secret en tu receptor de webhook para que verifique con el nuevo valor.

Deja que la ventana se cierre

Después de 24 horas, Ayrshare limpia automáticamente el secret anterior y firma solo con el nuevo secret. No es necesaria ninguna otra acción por tu parte.

Si rotas de nuevo mientras hay una ventana de gracia aún abierta, el secret recién sustituido se convierte en el nuevo secret anterior y se inicia una nueva ventana de 24 horas. Solo se guarda un secret anterior a la vez.

Verificación de firmas durante la ventana de gracia

Fuera de una ventana de gracia, las entregas firmadas llevan las cabeceras estándar (consulta Seguridad de webhook):

X-Authorization-Timestamp : <Unix Timestamp In Seconds>
X-Authorization-Content-SHA256 : <current-sig>
X-Authorization-Content-SHA256-V2 : v1=<current-sig>

Durante la ventana de 24 horas posterior a una rotación, la nueva cabecera X-Authorization-Content-SHA256-V2 lista ambas firmas, la actual primero, separadas por coma:

X-Authorization-Timestamp : <Unix Timestamp In Seconds>
X-Authorization-Content-SHA256 : <current-sig>
X-Authorization-Content-SHA256-V2 : v1=<current-sig>,v1=<previous-sig>

X-Authorization-Content-SHA256 no cambia: siempre lleva el único HMAC del secret actual, por compatibilidad hacia atrás. Las firmas duales solo aparecen en la nueva cabecera X-Authorization-Content-SHA256-V2.

Cada valor en X-Authorization-Content-SHA256-V2 va precedido por una etiqueta de esquema. v1= denota una firma HMAC-SHA256, calculada exactamente igual que X-Authorization-Content-SHA256. La cabecera -V2 siempre está presente cuando una entrega está firmada — lleva como mínimo v1=<current-sig> — por lo que puedes confiar en ella como un contrato estable del receptor. Para verificar una entrega durante (o fuera de) una rotación:

Calcula el HMAC

Calcula el HMAC-SHA256 del cuerpo raw de la solicitud usando tu signing secret configurado localmente.

Compara con todas las firmas listadas

Lee X-Authorization-Content-SHA256-V2, divídelo por comas, quita el prefijo v1= de cada valor y acepta la entrega como auténtica si tu HMAC calculado coincide con cualquier firma v1= listada.

Aceptar si cualquier firma listada coincide es lo que hace que la rotación sea sin downtime: un receptor todavía configurado con el secret antiguo coincide con v1=<previous-sig>, mientras que un receptor actualizado al nuevo secret coincide con v1=<current-sig> — ambos tienen éxito durante toda la ventana.

Ejemplo de verificación en el receptor

Node.js

import crypto from "crypto";

// secret es el signing secret actualmente configurado en tu receptor.
function isAuthenticWebhook(rawBody, headers, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody) // el cuerpo raw sin parsear de la solicitud
    .digest("hex");

  const headerValue = headers["x-authorization-content-sha256-v2"] || "";

  // Aceptar si CUALQUIER firma v1= de la cabecera coincide con nuestro HMAC calculado.
  return headerValue
    .split(",")
    .map((part) => part.trim())
    .filter((part) => part.startsWith("v1="))
    .map((part) => part.slice("v1=".length))
    .some((sig) => {
      const sigBuf = Buffer.from(sig);
      const expectedBuf = Buffer.from(expected);
      // timingSafeEqual lanza excepción si las longitudes no coinciden — tratarlo como no auténtico.
      return (
        sigBuf.length === expectedBuf.length &&
        crypto.timingSafeEqual(sigBuf, expectedBuf)
      );
    });
}

Calcula siempre el HMAC sobre los bytes raw del cuerpo de la solicitud, exactamente como se recibieron — no sobre un objeto JSON re-serializado. La re-serialización puede cambiar los espacios en blanco o el orden de las claves y romper la verificación. Usa una comparación en tiempo constante (como crypto.timingSafeEqual) para evitar timing attacks.

Si falta el registro del secret actual de una entrega, la entrega procede sin firma (sin cabeceras de firma) en lugar de fallar. Si solo falta el registro del secret anterior, la firma anterior se omite y la firma actual se sigue emitiendo en ambas cabeceras.

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Visión general

Rotar desde el Dashboard

Rotar mediante la API

Parámetros de cabecera

Parámetros del cuerpo

Procedimiento seguro de rotación

Verificación de firmas durante la ventana de gracia

Ejemplo de verificación en el receptor

​Visión general

​Rotar desde el Dashboard

​Rotar mediante la API

​Parámetros de cabecera

​Parámetros del cuerpo

​Procedimiento seguro de rotación

​Verificación de firmas durante la ventana de gracia

​Ejemplo de verificación en el receptor

Visión general

Rotar desde el Dashboard

Rotar mediante la API

Parámetros de cabecera

Parámetros del cuerpo

Procedimiento seguro de rotación

Verificación de firmas durante la ventana de gracia

Ejemplo de verificación en el receptor