Payloads de webhook

Los tipos de evento de los webhooks de Feedjolt y las cabeceras que enmarcan cada envío. Forma del payload, firma, idempotencia y estabilidad de campos.

Cada entrega de webhook es un POST application/json a tu endpoint. El cuerpo es el payload del evento - no hay envoltorio; el tipo de evento y la marca de tiempo van en cabeceras HTTP.

Cabeceras

Content-Type: application/json
X-Feedjolt-Signature: sha256=<hex>
X-Feedjolt-Event: status.changed
X-Feedjolt-Timestamp: 2026-04-30T12:34:56.789012+00:00

Bifurca por X-Feedjolt-Event en tu handler.

Tipos de evento

Evento	Cuándo
`post.created`	Se crea un nuevo post en un tablero al que estás suscrito.
`post.merged`	Un post se fusiona con otro.
`post.moderated`	Un borrador se aprueba o rechaza.
`status.changed`	Un post cambia de estado.
`comment.created`	Se publica un nuevo comentario (público o interno).
`vote.threshold`	Un post supera un umbral de votos configurado.

Estos son los tipos de evento actualmente soportados por el enum NotificationEventType del backend. Eventos adicionales (ediciones de posts, eliminaciones, ediciones de comentarios, publicaciones de changelog) están en la hoja de ruta - vótalos.

Forma del payload

El cuerpo es el mismo dict que usamos internamente para renderizar notificaciones. El conjunto exacto de campos varía por tipo de evento. Los esquemas viven en la referencia OpenAPI bajo la sección de webhooks, ya que comparten tipos con la API.

Un cuerpo representativo de status.changed se ve aproximadamente como:

{
  "id": "evt_abc123",
  "post": {
    "id": "post_xyz",
    "title": "Add dark mode",
    "url": "https://feedjolt.com/p/acme/posts/post_xyz",
    "board_slug": "feature-requests"
  },
  "from_status": { "name": "Planeado", "color": "#6366F1" },
  "to_status":   { "name": "En curso", "color": "#FB923C" },
  "actor":       { "type": "admin_user", "email": "[email protected]" }
}

Trata el campo id como clave de idempotencia - ver Reintentos.

Estabilidad de campos

Actualmente no versionamos los payloads de evento. Si necesitamos hacer un cambio rompiente, añadiremos un nuevo tipo de evento junto al viejo y migraremos a nuestro propio ritmo.
Podemos añadir campos a payloads existentes sin previo aviso. Programa defensivamente (no falles ante claves desconocidas).

Truncado

Los cuerpos largos (cuerpo de post, cuerpo de comentario) no se truncan hoy; enviamos el contenido completo. Si tu endpoint tiene límite de tamaño de petición, déjalo generoso. El timeout de entrega de 10 segundos es el primer fallo más probable.