Configuración de webhooks

Esta página cubre el manejo (alta, baja, modificación, prueba) de endpoints webhook. Para el modelo conceptual y la seguridad, ver Conceptos → Webhooks.

Modelo

{
  "id": 301,
  "url": "https://erp.distribuidora-demo.com/maxpay/events",
  "events": [
    "receivable-account.activated",
    "receivable.created",
    "receivable.paid",
    "receivable.settled",
    "settlement.completed"
  ],
  "status": "ACTIVE",
  "secret": "whsec_aB3xY9mNpQ2rTzV5wK7jH8...",
  "secretMaskedTail": "...8fdK",
  "lastDeliveryAt": "2026-05-15T14:30:00-03:00",
  "lastDeliveryStatus": "SUCCESS",
  "creationDate": "2026-04-01T10:00:00-03:00",
  "modificationDate": "2026-05-15T14:30:00-03:00"
}

Campo	Tipo	Descripción
id	int64	ID del webhook
url	URL	Endpoint del integrador. Debe ser HTTPS
events	array	Eventos a los que está suscripto. Lista completa en Eventos
status	enum	ACTIVE, PAUSED, FAILED. Tras múltiples fallas consecutivas el webhook pasa a FAILED (umbral configurable).
secret	string	Secreto para verificar firma HMAC. Solo se devuelve al crear o rotar
secretMaskedTail	string	Últimos 4 caracteres del secret, para confirmar cuál está activo
lastDeliveryAt	ISO 8601	Última entrega
lastDeliveryStatus	enum	SUCCESS, FAILED

Endpoints

Método	Path	Descripción
GET	/v1/webhooks	Lista webhooks configurados
POST	/v1/webhooks	Crea un webhook
GET	/v1/webhooks/{id}	Detalle
PUT	/v1/webhooks/{id}	Actualiza URL o lista de eventos
DELETE	/v1/webhooks/{id}	Elimina
POST	/v1/webhooks/{id}/pauses	Pausa entregas
POST	/v1/webhooks/{id}/activations	Reanuda entregas
POST	/v1/webhooks/{id}/secret-rotations	Rota el secret (devuelve nuevo)
POST	/v1/webhooks/{id}/deliveries	Envía evento de prueba
GET	/v1/webhooks/{id}/deliveries	Historial de entregas

Crear un webhook

POST /v1/webhooks
Idempotency-Key: setup-erp-prod-001
Content-Type: application/json

{
  "url": "https://erp.distribuidora-demo.com/maxpay/events",
  "events": [
    "receivable-account.activated",
    "receivable.created",
    "receivable.paid",
    "receivable.settled",
    "settlement.completed"
  ]
}

Respuesta

201 Created
Location: /v1/webhooks/301

{
  "id": 301,
  "url": "https://erp.distribuidora-demo.com/maxpay/events",
  "events": [...],
  "status": "ACTIVE",
  "secret": "whsec_aB3xY9mNpQ2rTzV5wK7jH8nM4fdK",
  "secretMaskedTail": "...8fdK",
  ...
}

Guardá el secret ahora

El campo secret se devuelve una sola vez, al crear el webhook o al rotarlo. Después de este request, solo vas a ver secretMaskedTail. Si lo perdés, tenés que rotarlo con POST /webhooks/{id}/secret-rotations.

Pausar y reanudar

Para pausar temporalmente la recepción (mantenimiento, deploy):

POST /v1/webhooks/301/pauses

Los eventos generados mientras está pausado se retienen y se entregan cuando se reanuda. Hay una ventana de retención tras la cual los eventos retenidos se descartan.

POST /v1/webhooks/301/activations

Rotar el secret

Para rotar el secret (compromiso, política):

POST /v1/webhooks/301/secret-rotations

{
  "id": 301,
  "secret": "whsec_xY9mNpQ2rT...",
  "secretMaskedTail": "...4hLm",
  ...
}

Después de rotar, los próximos webhooks llegan firmados con el nuevo secret. Durante una ventana de gracia tras la rotación, las firmas con el secret anterior siguen siendo válidas para dar tiempo a actualizar la configuración en el ERP.

Diagnóstico de entregas

Test delivery

Para validar que tu endpoint funciona después de configurarlo:

POST /v1/webhooks/301/deliveries
Content-Type: application/json

{
  "eventType": "webhook.test"
}

Envía un evento de prueba al URL configurado y devuelve el resultado de esa entrega.

Historial de entregas

GET /v1/webhooks/301/deliveries?fromDate=2026-05-14&toDate=2026-05-15&status=FAILED

Filtros: fromDate, toDate, status, eventType, eventId. Paginación estándar. Cada entrega incluye eventId, eventType, attempt, status y el código de respuesta del endpoint.

Reenviar una entrega

Para reintentar una entrega fallida manualmente:

POST /v1/webhooks/301/deliveries
Content-Type: application/json

{
  "eventId": "evt_a1b2c3..."
}

Genera un nuevo intento de entrega del evento original. Útil cuando arreglaste el bug en tu endpoint y querés recuperar eventos perdidos.