Crear integraciones propias con webhooks

La regla «Publicar en Webhook» te permite automatizar el envío de nuevas publicaciones de feeds RSS al endpoint de webhook que indiques, en cuanto estén disponibles. También puedes definir qué publicaciones enviar mediante palabras clave y filtros. Cuando una publicación nueva cumple tus criterios, se envía al endpoint como una solicitud POST con formato JSON.

Formato de los datos JSON

Cada solicitud POST que se envía a tu webhook contiene dos elementos principales: post y feed.

También incluye metadatos para identificar el mensaje del webhook. El campo version indica qué versión de la API de webhooks de Feeder se está usando. La versión es siempre 2023-06-26 y se actualizará si se introducen cambios incompatibles.

{
  "version": "2023-06-26",
  "message_id": "a unique UUID for this message, will be constant during retries",
  "feed": { ... },
  "post": { ... }
}

El elemento post contiene información sobre la publicación:

{
  "id": "The unique identifier of the post",
  "title": "The title of the post",
  "url": "The URL where the post can be accessed",
  "published": "The date and time when the post was published",
  "content": "The content of the post",
  "audio_url": "link to mp3 attached to post (if present)",
  "image_url": "link to image attached to post (if present)
}

Nota: published tendrá el valor null si el feed RSS no especifica una fecha de publicación válida.

El elemento feed proporciona información sobre el feed del que procede la publicación:

{
  "id": "The unique identifier of the feed",
  "source_url": "The URL of the source, for example RSS/Atom feed URL",
  "public_url": "The source's self identified public URL",
  "title": "The title of the feed",
  "favicon": "The URL of the feed's favicon"
}

Es posible que en el futuro añadamos campos a estos objetos. Si echas algo en falta, avísanos.

Reintentos

Si una solicitud falla, Feeder la vuelve a intentar automáticamente. Si una solicitud POST no recibe un código de respuesta HTTP entre 200 y 399, intentaremos enviarla de nuevo según este calendario, expresado en segundos:

• Reintento 1: después de 5 segundos
• Reintento 2: después de 30 segundos
• Reintento 3: después de 60 segundos
• Reintento 4: después de 5 minutos
• Reintento 5: después de 10 minutos
• Reintento 6: después de 30 minutos
• Reintento 7: después de 30 minutos
• Reintento 8: después de 30 minutos

Ten en cuenta que este mecanismo de reintento solo se activa cuando se produce un evento real de publicación, y no se aplica a las notificaciones de prueba. Los intervalos también pueden cambiar.

Depuración

Si se producen errores, puedes consultarlos en el registro de ejecuciones de acciones. Solo tienes que abrir la regla que no funciona y pulsar «Open error log».

Ahí encontrarás más información sobre los webhooks que han fallado.

Configurar tu webhook

Para configurar tu webhook:

1. Ve a la página de Reglas.
2. Crea una regla nueva.
3. Indica el nombre, los feeds y los criterios.
4. En la sección «¿Qué debería suceder?», elige «Publicar en Webhook».
5. Escribe la URL del webhook en el campo correspondiente.
6. Para comprobar que todo está bien configurado, puedes pulsar el botón «Enviar mensaje de prueba» para enviar una notificación de prueba a tu endpoint. Ten en cuenta que es solo una prueba y, si falla, no se iniciará el mecanismo de reintentos. Además, para enviar la publicación de prueba, debes tener al menos 1 feed con publicaciones añadido a tu cuenta.

Seguridad: verificar las firmas de los webhooks

Para comprobar que las solicitudes entrantes del webhook proceden realmente de Feeder y no se han manipulado, puedes verificar el secreto del webhook que se genera para cada uno. Todas las solicitudes de webhook incluyen una cabecera X-Feeder-Signature con una firma HMAC-SHA256 del cuerpo de la solicitud.

Cómo funciona

1. En los ajustes de la regla, activa la opción «Avanzado». Verás una cadena en el campo «Secreto del webhook».
2. Cuando Feeder envía un webhook a tu endpoint, calcula un hash HMAC-SHA256 del cuerpo JSON de la solicitud y usa tu secreto como clave.
3. La firma resultante se envía en la cabecera X-Feeder-Signature, precedida por sha256=. Por ejemplo:

   X-Feeder-Signature: sha256=a1b2c3d4e5f6...

4. En tu servidor, vuelve a calcular el mismo hash HMAC-SHA256 con el cuerpo original de la solicitud y tu copia del secreto. Luego, compáralo con el valor de la cabecera.

¿Para qué sirve?

• Autenticidad: confirma que Feeder envió la solicitud y no un tercero.
• Integridad: garantiza que los datos no se hayan modificado durante el envío.

Verificar la firma

Para verificarla:

1. Lee el cuerpo original de la solicitud como una cadena de texto, sin analizarlo antes.
2. Calcula el HMAC-SHA256 de esa cadena con tu secreto.
3. Compara la firma calculada con el valor de la cabecera X-Feeder-Signature mediante una comparación segura frente a ataques de temporización.

Ejemplo: Node.js (Express)

const crypto = require("crypto");

const WEBHOOK_SECRET = process.env.FEEDER_WEBHOOK_SECRET;

function verifyFeederSignature(req, res, next) {
  const signature = req.headers["x-feeder-signature"];
  if (!signature) {
    return res.status(401).send("Missing signature");
  }

  const expectedSignature =
    "sha256=" +
    crypto.createHmac("sha256", WEBHOOK_SECRET).update(req.body).digest("hex");

  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  next();
}

// Important: use express.raw() so req.body is the raw string, not parsed JSON
app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  verifyFeederSignature,
  (req, res) => {
    const payload = JSON.parse(req.body);
    // Handle the webhook payload
    console.log("Received verified webhook:", payload);
    res.sendStatus(200);
  }
);

Importante: para verificar la firma, debes acceder al cuerpo original de la solicitud. Si el framework analiza el cuerpo JSON antes de que calcules el HMAC, la cadena que se vuelva a generar podría ser distinta de la original y la firma no coincidirá. En Express, usa express.raw({ type: "application/json" }) en la ruta del webhook, como se muestra arriba.

¿Algo más?

¿Tienes preguntas? Escríbenos a support@feeder.co.