Webhook de retroalimentación

Le notificamos vía webhook cuando Spot2 Ingestion acepta una propiedad para procesamiento o la rechaza por errores bloqueantes. El webhook es opcional: sus propiedades se procesan igual sin él, pero no recibe retroalimentación automática de aceptación o rechazo.

---

Endpoint que nos da

Exponga un endpoint HTTP POST que reciba JSON:

POST /api/webhooks/spot2/feedback HTTP/1.1
Host: su-crm.com
Content-Type: application/json
Authorization: Bearer <feedback-token>

Debe responder con cualquier status 2xx cuando procese el webhook correctamente.

---

Autenticación del webhook

Cada request incluye un token bearer compartido:

Authorization: Bearer <feedback-token>

Para verificarlo:

1. Extraiga el token del header Authorization.
2. Compare el token recibido contra el valor acordado.
3. Si coincide, procese el webhook.
4. Si no coincide, responda 401 y descarte el request.

Si necesita rotar el token, coordínelo con Spot2 para evitar rechazos durante la transición.

---

Estados emitidos por Ingestion

Spot2 Ingestion emite solo estados de etapa de ingestión:

Estado	Cuándo ocurre	Campos
PROCESSING	La propiedad fue aceptada por Ingestion y enviada al flujo downstream de publicación.	external_id, status
REJECTED	La propiedad no puede continuar por un error bloqueante de mapeo, enriquecimiento, QA, preparación o publicación.	external_id, status, messages

Los estados finales del marketplace, como publicado, despublicado o archivado, pertenecen a servicios downstream y no forman parte de este webhook estándar de Ingestion.

---

Payload PROCESSING

La propiedad fue aceptada para procesamiento. Este estado no significa que ya esté publicada en el marketplace.

{
  "external_id": "PROP-001",
  "status": "PROCESSING"
}

Campo	Tipo	Descripción
external_id	string	Identificador de la propiedad en su sistema.
status	string	Siempre PROCESSING.

---

Payload REJECTED

La propiedad no puede continuar por errores bloqueantes. Corrija los datos en su CRM para que se reprocese en un ciclo posterior.

{
  "external_id": "PROP-002",
  "status": "REJECTED",
  "messages": [
    "Al menos un precio (renta o venta) debe ser mayor a cero",
    "location.latitude y location.longitude son obligatorios",
    "contact.name, contact.email y contact.phone son obligatorios",
    "No se pudo resolver zip_code_id para el código postal: 00000"
  ]
}

Campo	Tipo	Descripción
external_id	string	Identificador de la propiedad en su sistema.
status	string	Siempre REJECTED.
messages	string[]	Mensajes legibles con los errores bloqueantes.

messages solo incluye problemas BLOCK. Hallazgos DRAFT y la regla WARN de amenidades no se envían como rechazo en este webhook.

---

Idioma de los mensajes

Por defecto enviamos mensajes en español. Si necesita mensajes en inglés, podemos configurarlo por integración.

---

Reintentos

La entrega del webhook es asíncrona. Si su endpoint no responde con 2xx, hacemos hasta 3 intentos totales con backoff:

Intento	Espera aproximada
1	Inmediato
2	10 segundos
3	30 segundos

Si los reintentos se agotan, abandonamos la entrega y registramos el fallo. Esto no detiene el ciclo de ingestión ni afecta la publicación de la propiedad.

---

Respuestas esperadas

Código	Cuándo usarlo
2xx	Webhook recibido correctamente.
401	Token bearer inválido.
429	Rate limit temporal. Se reintentará.
5xx	Error temporal del servidor. Se reintentará.

---

Seguridad

• Use HTTPS siempre.
• Valide el token bearer en cada request.
• No exponga el feedback_token en logs, código fuente o URLs.
• Procese el webhook de forma idempotente por external_id y status.