Contrato de entrega de artículos
Referencia para desarrolladores que reciben artículos publicados completos.
Usa una clave distinta por receptor. Las claves se almacenan cifradas y nunca se devuelven en los resúmenes de conexión. Autentica mediante la firma antes de confiar en el identificador del sitio.
Solicitud y verificación
Structura envía HTTPS POST con Content-Type: application/json, X-Structura-Event-Id, X-Structura-Timestamp (segundos Unix) y X-Structura-Signature (sha256= seguido de un digest hexadecimal en minúsculas). Calcula HMAC-SHA256 de timestamp + "." + rawBody con la clave en UTF-8. Compara bytes de igual longitud en tiempo constante, rechaza diferencias de más de cinco minutos y después analiza el JSON. El ID del encabezado debe coincidir con el cuerpo. No vuelvas a serializar JSON para verificar la firma.
Formato del mensaje
{
"schema_version": 1,
"event": "post.published",
"event_id": "article_<sha256>",
"delivered_at": "2026-09-28T10:00:00.000Z",
"site": {
"id": "site_123"
},
"post": {
"id": "post_123",
"slug": "first-article",
"title": "First article",
"html": "<p>Article body</p>",
"markdown": "Article body",
"excerpt": null,
"metaTitle": null,
"metaDescription": null,
"focusKeyword": null,
"locale": "en",
"publishedAt": "2026-09-28T10:00:00.000Z",
"updatedAt": "2026-09-28T10:00:00.000Z",
"canonicalUrl": "https://example.com/blog/first-article",
"featuredImage": null,
"author": null,
"jsonLd": []
}
}id es texto para artículos headless o un número para WordPress. Los metadatos ausentes son null; jsonLd es una matriz. El HTML está saneado y Markdown se genera desde ese HTML. El idioma del contenido no depende de las notificaciones. Las imágenes permanecen alojadas en sus URL. Solo se incluye la identidad pública del autor cuando la fuente la proporciona.
Antes de insertar jsonLd en un elemento <script type="application/ld+json">, serialízalo y sustituye cada < por \u003c. Un JSON válido puede contener </script>; sanear el HTML no hace seguro insertar ese JSON directamente.
La solicitud completa admite un máximo de 1.000.000 bytes UTF-8, incluidos HTML, Markdown, metadatos y escapes JSON. La normalización permite 995.904 bytes para el artículo y reserva 4.096 bytes para el evento. Los artículos mayores se omiten con article_too_large; usa la Content API para contenido más grande.
Almacenamiento y entrega
Impón una restricción única duradera sobre event_id. En la misma transacción, actualiza por site.id, post.id y post.locale, y marca el evento como procesado. Confirma tras el commit. Un duplicado válido devuelve 2xx sin volver a aplicarse. Compara updatedAt para no sobrescribir una revisión nueva con una antigua. Los ID incluyen identidad del espacio, sitio y contenido; una revisión republicada tiene otro ID.
Cualquier 2xx indica éxito. Los errores de red y HTTP 408, 429 y 5xx tienen un reintento tras 150 ms. Los demás fallan inmediatamente. Cada intento dura como máximo 8 segundos; el cuerpo de respuesta se ignora. No hay repetición automática posterior. Se rechazan redirecciones, direcciones privadas y receptores sin HTTPS. Guarda primero y procesa el trabajo pesado en tu propia cola.
Solo la publicación genera un envío. Las ediciones y eliminaciones no generan eventos. Usa la Content API pública para reconciliar publicaciones perdidas o cambios. WordPress requiere un plugin que envíe el campo opcional article; los antiguos siguen enviando otras notificaciones, pero no artículos completos.