Webhook de retroalimentación

Le notificamos vía webhook cuando una propiedad es aceptada o rechazada. El webhook es opcional: sus propiedades se publican igual sin él, pero no recibe notificaciones de rechazo.

---

Endpoint que nos da

Un endpoint HTTP POST que reciba JSON:

POST https://su-crm.com/api/webhooks/spot2/feedback

Debe responder 2xx en menos de 10 segundos.

---

Autenticación del webhook (HMAC)

Para que pueda verificar que los requests vienen de Spot2 y no fueron alterados, cada request incluye un header X-Signature con un HMAC-SHA256 del cuerpo.

Cómo funciona

1. Nos da un secreto compartido (feedback_secret).

2. Cada request que enviamos incluye el header:

   X-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

3. Para verificar, su servidor debe:

   • Tomar el cuerpo crudo del request (bytes, sin parsear).
   • Calcular HMAC-SHA256 usando su secreto como clave.
   • Comparar el hash resultante (en hexadecimal, prefijado con sha256=) contra el valor del header.
   • Usar comparación timing-safe (constant-time).

Si la firma no coincide, el request no es legítimo. Rechácelo con 401.

Rotación del secreto

Si necesita rotar el secreto, coordínelo con nosotros. Podemos configurar una ventana de transición donde aceptemos ambos secretos (viejo y nuevo) para evitar rechazos durante el cambio.

---

Reintentos

Si su endpoint no responde 2xx, reintentamos hasta 5 veces con backoff:

• Intento 1: inmediato.
• Intento 2: 10 segundos después.
• Intento 3: 1 minuto después.
• Intento 4: 5 minutos después.
• Intento 5: 30 minutos después.

Si los 5 intentos fallan, se abandona la entrega. No afecta la publicación de la propiedad.

---

Idioma de los mensajes

Por defecto los mensajes de rechazo se envían en español. Si necesita los mensajes en inglés, podemos configurarlo por plataforma.

---

Eventos

Emitimos dos eventos: item_rejected y item_accepted.

item_rejected

La propiedad no se publicó. Incluye los motivos del rechazo.

Payload enviado:

{
  "external_id": "prop-12345",
  "status": "REJECTED",
  "messages": [
    "Precio de renta (5000 MXN) por debajo del mínimo (10000 MXN)",
    "La propiedad no tiene fotos"
  ]
}

Campo	Tipo	Descripción
external_id	string	Su identificador de propiedad.
status	string	Siempre "REJECTED".
messages	string[]	Motivos del rechazo en lenguaje natural.

item_accepted

La propiedad se publicó correctamente en Spot2.

Payload enviado:

{
  "external_id": "prop-12346",
  "status": "PROCESSING"
}

Campo	Tipo	Descripción
external_id	string	Su identificador de propiedad.
status	string	"PROCESSING" (Spot2 está procesando la publicación).

---

Seguridad

• Use HTTPS siempre.
• Valide la firma HMAC en cada request.
• No exponga el feedback_secret en logs, código fuente, o URLs.
• Si su endpoint está caído, los webhooks se pierden después de 5 reintentos. No hay cola de reintentos histórica.