> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.ntxpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuración de Webhooks

> Registra, prueba, lista y elimina URLs de webhook programáticamente

## Visión General

La configuración de webhooks se hace vía cuatro endpoints:

* `GET /api/webhooks-config` — listar webhooks activos
* `POST /api/webhooks-config` — crear/configurar un webhook
* `POST /api/webhooks-config/test` — disparar un webhook de prueba firmado
* `DELETE /api/webhooks-config/{id}` — eliminar un webhook

## Crear Webhook

### Request

```bash theme={"system"}
curl -X POST https://sandbox.mx.ntxpay.com/api/webhooks-config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meu-servidor.com/webhooks/ntxpay",
    "events": ["cash_in"],
    "secret": "whsec_abc123def456"
  }'
```

### Response (201)

```json theme={"system"}
{
  "id": 42,
  "url": "https://meu-servidor.com/webhooks/ntxpay",
  "events": ["cash_in"],
  "isActive": true,
  "secret": "whsec_abc123def456"
}
```

<Warning>
  Si omites `secret` en el request, NTX Pay lo genera automáticamente y lo devuelve en la respuesta — **guárdalo de inmediato**, no se muestra de nuevo.
</Warning>

### Campos

<ParamField path="url" type="string" required>
  URL HTTPS del endpoint que recibirá los webhooks. **HTTP simple es rechazado.**
</ParamField>

<ParamField path="events" type="array" required>
  Un webhook se suscribe a **exactamente UN** evento — el array debe contener un único elemento. Valores aceptados: `cash_in`, `cash_out`, `refund_in`, `refund_out`, `all` (General — recibe todos los eventos) e `internal_transfer`. Consulta la semántica de cada tipo en la [Visión General](/es/guides/webhooks/overview).
</ParamField>

<ParamField path="secret" type="string">
  Secret HMAC para validar la firma. Mínimo 8 caracteres, máximo 128. Si se omite, NTX Pay lo genera.
</ParamField>

## Webhook de Prueba

Después de crear el webhook, dispara una entrega de prueba **firmada con el mismo secret** — sin necesidad de mover una transacción:

```bash theme={"system"}
curl -X POST https://sandbox.mx.ntxpay.com/api/webhooks-config/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "cash_in",
    "status": "LIQUIDATED"
  }'
```

```json theme={"system"}
{
  "delivered": true,
  "url": "https://meu-servidor.com/webhooks/ntxpay",
  "eventId": "8e2c5b6f-3a12-4b9c-9a18-77a2b3c4d5e6",
  "status": "LIQUIDATED",
  "signed": true,
  "statusCode": 200,
  "timeMs": 184
}
```

<ParamField path="eventType" type="string" required>
  Qué webhook recibe la prueba: `cash_in`, `cash_out`, `refund_in`, `refund_out` o `internal_transfer`.
</ParamField>

<ParamField path="status" type="string">
  Status simulado en el payload: `LIQUIDATED` (default), `PENDING`, `REJECTED` o `RETURNED`.
</ParamField>

<ParamField path="overrideUrl" type="string">
  URL temporal de prueba (ej.: webhook.site). Si se omite, entrega en la URL configurada.
</ParamField>

<ParamField path="amountCentavos" type="integer">
  Monto en centavos en el payload de prueba (default `1000` = \$10.00 MXN).
</ParamField>

`delivered: true` significa que tu endpoint respondió `2xx`. `statusCode: 0` indica error de conexión.

## Listar Webhooks

```bash theme={"system"}
curl -X GET https://sandbox.mx.ntxpay.com/api/webhooks-config \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={"system"}
{
  "accountId": 93,
  "webhooks": [
    {
      "id": 42,
      "url": "https://meu-servidor.com/webhooks/ntxpay",
      "events": ["cash_in"],
      "isActive": true,
      "createdAt": "2026-05-01T10:30:00.000Z"
    }
  ],
  "total": 1
}
```

<Info>
  La respuesta del listado **no** incluye el `secret` — solo se muestra en la creación.
</Info>

## Eliminar Webhook

```bash theme={"system"}
curl -X DELETE https://sandbox.mx.ntxpay.com/api/webhooks-config/42 \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={"system"}
{
  "success": true,
  "message": "Webhook removido com sucesso"
}
```

## Múltiples Webhooks

Cada webhook se suscribe a exactamente un evento, así que tienes dos estrategias:

* **Un webhook por tipo** (ej.: uno para `cash_in`, otro para `cash_out`) — enruta cada tipo a su propio endpoint/handler.
* **Un webhook `all`** — una URL única recibe todo y tu handler enruta por el campo `event` del payload.

## Validar el Endpoint

Antes de liberar el webhook para recibir tráfico real:

1. Usa [webhook.site](https://webhook.site) o [ngrok](https://ngrok.com) para inspeccionar el tráfico (el campo `overrideUrl` del webhook de prueba acepta esas URLs)
2. Dispara entregas con `POST /api/webhooks-config/test` variando el `status`
3. Verifica que tu aplicación:
   * Valida `X-NTXPay-Signature` correctamente
   * Devuelve `200` en menos de 10 segundos
   * Deduplica por `x-event-id`

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Implementación" href="/es/guides/webhooks/implementation">
    Validación HMAC en Node.js, Python, Java y Go
  </Card>

  <Card title="Eventos" href="/es/guides/webhooks/cash-in">
    Payload de cada tipo de evento
  </Card>
</CardGroup>