Webhooks

Los webhooks permiten que tu sistema reciba eventos de Polimake cuando ocurre algo relevante: un archivo se sube, el analisis IA termina, un activo cambia de estado o una pieza queda aprobada.

Estado: contrato preview. Los webhooks pueden estar disponibles solo bajo acuerdo o beta privada.

Eventos previstos

Evento	Cuando ocurre
media.uploaded	Un archivo se ha subido correctamente.
media.analysis.completed	El analisis IA de un media object ha terminado.
media.updated	Cambia metadata, estado o campos relevantes.
media.deleted	Un media object se elimina o se marca como eliminado.
workflow.status_changed	Un activo cambia de estado en un workflow.
workflow.approved	Un activo o pieza queda aprobada.

Payload

{
  "id": "evt_01HX9T3VZV8R",
  "object": "event",
  "type": "media.analysis.completed",
  "created_at": "2026-06-04T10:03:00Z",
  "data": {
    "object": {
      "id": "media_01HX9R8K4Q2Z4T",
      "object": "media_object",
      "project_id": "brand-assets",
      "status": "ready"
    }
  }
}

Verificacion

Cuando la firma de webhooks este disponible, cada peticion incluira una cabecera similar a:

Polimake-Signature: t=1780567380,v1=SIGNATURE

La integracion debe verificar la firma antes de confiar en el evento.

Respuesta esperada

Tu endpoint debe responder 2xx cuando el evento se procesa correctamente.

HTTP/1.1 200 OK

Si tu sistema devuelve 5xx, Polimake podra reintentar el evento segun la politica de reintentos configurada.

Buenas practicas

• Responde rapido y procesa trabajos pesados en background.
• Haz que el handler sea idempotente usando el campo id del evento.
• Guarda eventos recibidos para poder auditar integraciones.
• No dependas de que los eventos lleguen exactamente una vez.
• Si necesitas estado definitivo, consulta el media object por API despues de recibir el webhook.