Primeros pasos

Para recibir webhooks necesita un endpoint HTTPS público y una suscripción registrada por IDBI. Al registrarla, IDBI le entrega el secreto con el que verificará la firma de cada envío.

Ruta rápida

1. Prepare su endpoint.

   Publique una URL con HTTPS que acepte POST con Content-Type: application/json y responda con un código 2xx. Revise los requisitos.

2. Solicite la integración a IDBI.

   Las suscripciones las registra IDBI; usted no se registra por su cuenta. Consulte qué debe indicar.

3. Reciba el secreto.

   IDBI se lo entrega al registrar la suscripción; después no se puede volver a consultar. Guárdelo como variable de entorno o en un gestor de secretos.

4. Implemente la verificación de la firma.

   Siga Autenticación y firma. Verifique siempre sobre el cuerpo crudo de la petición.

5. Pruebe con el vector de prueba.

   Compruebe que su código reproduce la firma del vector de prueba antes de recibir envíos reales.

6. Salga a producción.

   Complete el checklist.

Requisitos del endpoint

Requisito	Detalle
Protocolo	HTTPS. No se aceptan URLs http://.
Accesibilidad	URL pública, alcanzable desde internet. Debe resolverse por DNS a una dirección IP pública: no se aceptan direcciones privadas ni reservadas, como localhost.
Método y formato	POST con cuerpo JSON (Content-Type: application/json).
Respuesta	Código 2xx dentro del tiempo de espera de su suscripción: 30 segundos por defecto, configurable entre 1 y 60 segundos.
Redirecciones	No las use. IDPOS puede seguirlas, pero no garantiza que se conserven el método POST ni el cuerpo. Registre la URL final.

Cómo se solicita la integración

Las suscripciones las registra IDBI; usted no puede crearlas por su cuenta. Solicite la integración a IDBI con estos datos:

Dato	Descripción
URL del endpoint	La URL pública HTTPS donde recibirá los envíos. No se aceptan direcciones privadas ni reservadas.
Tiendas	Las tiendas de IDPOS cuyos eventos desea recibir.
Eventos	Los eventos que desea recibir.

Cada suscripción pertenece a una sola tienda y tiene su propio secreto. Si necesita recibir los eventos de varias tiendas, IDBI registra una suscripción por tienda, cada una con su secreto. Si necesita varias URLs para una misma tienda, cada una se registra como una suscripción distinta.

Una URL por suscripción

Como cada suscripción tiene su secreto, use una URL distinta para cada una (por ejemplo, una ruta por tienda). Así sabe qué secreto aplicar antes de verificar la firma.

Qué recibe de IDBI

Elemento	Descripción
Secreto de la suscripción	Cadena con la que se calcula la firma HMAC-SHA256 de cada envío. IDPOS la genera al registrar la suscripción y solo la muestra en ese momento.

El secreto se entrega una sola vez

Guárdelo apenas lo reciba. No lo incluya en el código fuente, en repositorios ni en registros: quien lo conozca puede falsificar envíos hacia su endpoint. El secreto no se puede volver a consultar ni cambiar. Si lo pierde o sospecha que se expuso, comuníquese con IDBI: se registra una suscripción nueva, con un secreto nuevo, y se desactiva la anterior.

Checklist de salida a producción

• El endpoint es público, usa HTTPS y no redirige.
• El secreto está almacenado fuera del código fuente.
• La firma se verifica sobre el cuerpo crudo, con comparación en tiempo constante.
• Se rechazan los envíos cuyo X-Webhook-Timestamp difiere en más de 300 segundos de la hora de su servidor.
• El endpoint responde 2xx de inmediato y procesa el evento en segundo plano.
• Los eventos duplicados se descartan, después de verificar la firma, usando el event_id del cuerpo y, como segunda clave, event_type junto con data.id.
• La integración no depende del orden de llegada de los eventos.
• La integración ignora los campos que no reconoce.
• Reproduce el vector de prueba de la firma.

Siguiente paso

Continúe con Autenticación y firma o conozca los eventos.