# Uso de Webhooks en Verificamex

Fuente: /webhooks/using-webhooks-in-verificamex/

Configurar webhooks te permite automatizar procesos en tu backend al recibir notificaciones instantáneas sobre cambios de estado en tus verificaciones, eliminando la necesidad de realizar consultas constantes a nuestra API (Polling).

> **Ejemplo de uso con sesiones de verificación**
>
> Aquí te mostramos un ejemplo conceptual de cómo configurar un webhook en las diferentes endpoints disponibles.

### Configuración del Webhook

Para empezar a recibir eventos, debes proporcionar una URL válida al momento de iniciar una sesión de verificación.

1. **Define tu Endpoint**: Prepara una URL en tu servidor (ej. `https://tu-api.com/webhooks/callback`) que acepte solicitudes `POST` con cuerpo JSON.
2. **Parámetro `webhook`**: Al consumir el endpoint de [Crear Sesión de Verificación](/identity-verification/create-verification-session), incluye la URL en el cuerpo de la petición.
3. **Parámetro `with_webhook_binaries` (Opcional)**: Establece este valor en `true` si deseas que el payload incluya las imágenes (Selfie e INE) codificadas en Base64.

***

### Ejemplo de Solicitud

A continuación se muestra cómo registrar un webhook al crear una sesión:

**JSON**

```json
{
  "validations": "INE",
  "redirect_url": "https://tusitio.com/finalizado",
  "webhook": "https://tu-api.com/v1/webhooks/verificamex",
  "with_webhook_binaries": false
}
```

**cURL**

```bash
curl -X POST https://api.verificamex.com/identity/v2/identity/sessions \
  -H "Authorization: Bearer {TU_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "validations": "INE",
    "webhook": "https://tu-api.com/v1/webhooks/verificamex",
    "with_webhook_binaries": true
  }'
```

***

### Estructura del Payload (Notificación)

Cuando una sesión de verificación cambia su estado a `CLOSED`, Verificamex enviará un `POST` a tu URL con el resultado final:

```json
{
    "data": {
        "object": "VerificationSession",
        "id": "9d805854-f8a1-4135-ad57-3629ca0fc679",
        "status": "CLOSED",
        "result": "SUCCESS",
        "validations": ["INE", "CURP"],
        "ine": {
            "status": true,
            "data": { ... }
        },
        "renapo": {
            "status": true,
            "data": { ... }
        },
        "created_at": "2024-11-16T08:27:13.000000Z"
    }
}
```

> **Consejo**
>
> El payload del webhook sigue la misma estructura que la respuesta del endpoint **Mostrar sesión de verificación**.

***

### Mejores Prácticas y Seguridad

**Respuesta 200 OK**

Tu servidor debe responder con un código HTTP `200` para confirmar la recepción exitosa.

**Verifica la firma**

Cada webhook va firmado con tu clave. Verifica los headers `webhook-*` antes de procesarlo; consulta [Verificar la firma de los webhooks](/webhooks/webhooks-security/).

**Idempotencia**

Diseña tu lógica para manejar posibles reintentos de un mismo evento sin duplicar acciones en tu base de datos. Un reintento trae el mismo header `webhook-id`.

**Procesamiento Async**

Si el procesamiento de los datos es pesado, te recomendamos usar una cola de mensajes (Redis, RabbitMQ) y responder rápido al webhook.

**HTTPS Requerido**

Por seguridad, solo enviamos notificaciones a URLs que utilicen el protocolo cifrado HTTPS.

> **Importante**
>
> Asegúrate de que tu firewall o servicios como Cloudflare permitan peticiones entrantes si aplicas restricciones estrictas.