Webhook endpoints

CRUD sobre las URLs a las que Finova te avisa. Para entender el sobre, la firma, los reintentos y la lista de eventos, empieza por la guía de webhooks — esta página es la referencia del recurso.

El objeto WebhookEndpoint

{
  "id":               "65f0a1f1234567890abcdef0",
  "object":           "webhook_endpoint",
  "url":              "https://tu-servidor.com/webhooks/finova",
  "description":      "Portal de clientes",
  "enabled_events":   ["sale.paid", "recurring.occurrence_created", "invoice.*"],
  "active":           true,
  "secret_last_four": "a91c",

  "consecutive_failures": 0,
  "last_delivery_at":     "2026-09-17T18:04:12Z",
  "last_delivery_status": "succeeded",
  "disabled_at":          null,
  "disabled_reason":      null,

  "created_at": "2026-09-01T10:00:00Z",
  "updated_at": "2026-09-17T18:04:12Z"
}

Campo	Tipo	Descripción
url	string	Destino. https obligatorio en producción.
description	string	Para ti: qué integración es.
enabled_events	array	A qué te suscribes. Admite invoice.* y *.
active	bool	false deja de entregar sin perder la configuración.
secret_last_four	string	Últimos 4 caracteres del secreto, para reconocerlo.
consecutive_failures	int	Fallos seguidos. A los 20, Finova lo desactiva.
last_delivery_at / last_delivery_status	string	El último intento.
disabled_at / disabled_reason	string	Con valor: Finova dejó de intentarlo.

secret aparece sólo en la respuesta de create y de rotate-secret.

---

Listar

GET/api/v1/webhook-endpointsread-webhook_endpoints

El meta incluye available_events: la lista completa de eventos que Finova sabe emitir hoy.

---

Obtener uno

GET/api/v1/webhook-endpoints/:idread-webhook_endpoints

---

Crear

POST/api/v1/webhook-endpointscreate-webhook_endpoints

Requeridos: url, enabled_events (no puede ir vacío).

curl -X POST https://developers.fi-nova.com/api/v1/webhook-endpoints \
  -H 'Authorization: Bearer finova_sk_TU_SECRETO' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "url": "https://tu-servidor.com/webhooks/finova",
      "enabled_events": ["sale.paid", "recurring.occurrence_created"],
      "description": "Portal de clientes"
    }
  }'

Guarda el secret ahora

Es la única respuesta en la que aparece. Si lo pierdes, tendrás que rotarlo.

Un evento desconocido en enabled_events devuelve 422. Es deliberado: un endpoint suscrito a algo que no existe es un error de integración que vale más cazar aquí que seis meses después, preguntándote por qué no llega nada.

---

Actualizar

PUT/api/v1/webhook-endpoints/:idupdate-webhook_endpoints

Cambia url, description, enabled_events o active.

Reactivar (active: true) un endpoint que Finova apagó pone el contador de fallos a cero. Si no, el primer error posterior —un despliegue, un 502 de paso— lo tumbaría otra vez al instante.

---

Eliminar

DELETE/api/v1/webhook-endpoints/:iddelete-webhook_endpoints

Para pausar temporalmente, mejor active: false: conserva la configuración y el secreto.

---

Rotar el secreto

POST/api/v1/webhook-endpoints/:id/rotate-secretcreate-webhook_endpoints

Devuelve el endpoint con un secret nuevo. El cambio es inmediato.

---

Historial de entregas

GET/api/v1/webhook-endpoints/:id/deliveriesread-webhook_endpoints

Filtros: event, status (pending, succeeded, failed, exhausted).

{
  "data": [
    {
      "id":              "65f0b2e1234567890abcdef1",
      "object":          "webhook_delivery",
      "endpoint_id":     "65f0a1f1234567890abcdef0",
      "event":           "sale.paid",
      "event_id":        "evt_9c1f4a2b7e0d3f6a8b5c2d1e4f7a0b3c",
      "status":          "pending",
      "attempts":        2,
      "max_attempts":    6,
      "next_attempt_at": "2026-09-17T18:11:00Z",
      "delivered_at":    null,
      "response_status": 502,
      "error_message":   null,
      "created_at":      "2026-09-17T18:04:11Z"
    }
  ],
  "meta": { "limit": 25, "has_more": false }
}

Las entregas se conservan 30 días.