⚠️ AVISO: Los webhooks están disponibles en los planes Avanzado y Total.

La API de webhooks te permite gestionar endpoints, consultar eventos y reenviar notificaciones de forma programática. Puedes crear endpoints, suscribirte a eventos, revisar el historial de envíos y rotar signing secrets, todo mediante la API.

💡 Recomendación: Antes de empezar a desarrollar, te recomendamos crear un entorno de pruebas (sandbox) para hacer tus primeras llamadas sin afectar tus datos reales.

Autenticación

La API de webhooks acepta dos métodos de autenticación:

API Key: añade la cabecera facturadirecta-api-key: TU_CLAVE_API. La clave debe tener los permisos webhooks:read y/o webhooks:write
OAuth2: solicita los scopes webhooks:read y/o webhooks:write en el flujo de autorización

Endpoints de gestión

Método	Endpoint	Descripción	Scope
GET	/{companyId}/webhooks/endpoints	Listar endpoints	`webhooks:read`
POST	/{companyId}/webhooks/endpoints	Crear endpoint	`webhooks:write`
GET	/{companyId}/webhooks/endpoints/{endpointId}	Obtener endpoint	`webhooks:read`
PUT	/{companyId}/webhooks/endpoints/{endpointId}	Actualizar endpoint	`webhooks:write`
DELETE	/{companyId}/webhooks/endpoints/{endpointId}	Eliminar endpoint	`webhooks:write`
POST	/{companyId}/webhooks/endpoints/{endpointId}/enable	Reactivar endpoint	`webhooks:write`
POST	/{companyId}/webhooks/endpoints/{endpointId}/disable	Desactivar endpoint	`webhooks:write`
POST	/{companyId}/webhooks/endpoints/{endpointId}/rotate-secret	Rotar signing secret	`webhooks:write`

Endpoints de eventos

Método	Endpoint	Descripción	Scope
GET	/{companyId}/webhooks/events	Listar eventos (paginación por cursor)	`webhooks:read`
GET	/{companyId}/webhooks/events/{eventId}	Obtener evento	`webhooks:read`
POST	/{companyId}/webhooks/events/{eventId}/retry	Reenviar evento	`webhooks:write`

Ejemplos de código

Crear un endpoint

curl -X POST \
  -H "facturadirecta-api-key: TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-servidor.com/webhook",
    "name": "Integración ERP",
    "events": ["invoice.created", "invoice.updated", "contact.created"]
  }' \
  https://app.facturadirecta.com/api/TU_COMPANY_ID/webhooks/endpoints

La respuesta incluye el signing secret (solo se muestra en este momento):

{
  "data": {
    "id": "wep_abc123",
    "url": "https://tu-servidor.com/webhook",
    "name": "Integración ERP",
    "events": ["invoice.created", "invoice.updated", "contact.created"],
    "status": "active",
    "secret": "whsec_a1b2c3d4e5f6..."
  }
}

Listar endpoints

curl -H "facturadirecta-api-key: TU_CLAVE_API" \
  https://app.facturadirecta.com/api/TU_COMPANY_ID/webhooks/endpoints

Consultar eventos

curl -H "facturadirecta-api-key: TU_CLAVE_API" \
  "https://app.facturadirecta.com/api/TU_COMPANY_ID/webhooks/events?endpoint_id=wep_abc123&status=failed&limit=10"

Reenviar un evento

curl -X POST \
  -H "facturadirecta-api-key: TU_CLAVE_API" \
  https://app.facturadirecta.com/api/TU_COMPANY_ID/webhooks/events/whe_xyz789/retry

Rotar signing secret

curl -X POST \
  -H "facturadirecta-api-key: TU_CLAVE_API" \
  https://app.facturadirecta.com/api/TU_COMPANY_ID/webhooks/endpoints/wep_abc123/rotate-secret

La respuesta incluye el nuevo signing secret:

{
  "data": {
    "id": "wep_abc123",
    "secret": "whsec_nuevo_secret..."
  }
}

Campos del endpoint

Campo	Tipo	Descripción
`id`	string	ID único del endpoint (formato `wep_<id>`)
`url`	string	URL HTTPS de destino
`name`	string	Nombre descriptivo del endpoint
`events`	array	Lista de tipos de evento suscritos
`status`	string	`active` o `disabled`
`failure_count`	number	Número de fallos consecutivos (se resetea a 0 al reactivar)
`last_sent_at`	string \| null	Fecha del último envío
`created_at`	string	Fecha de creación
`secret`	string	Signing secret (solo en la respuesta de crear o rotar)

Campos del evento

Campo	Tipo	Descripción
`id`	string	ID único del evento (formato `whe_<uuid>`)
`type`	string	Tipo de evento (ej: `invoice.created`)
`status`	string	Estado del evento: `pending`, `delivered`, `failed` o `disabled`
`endpoint_id`	string	ID del endpoint al que se envió
`created`	number	Timestamp Unix del evento (en segundos)
`livemode`	boolean	`true` en producción, `false` en sandbox
`data`	object	Payload del evento (snapshot del documento)
`http_status`	number \| null	Código HTTP de la última respuesta
`attempts`	number	Número de intentos de entrega realizados

Filtros de eventos

Al listar eventos (GET /{companyId}/webhooks/events) puedes usar los siguientes filtros:

Parámetro	Tipo	Descripción
`endpoint_id`	string	Filtrar por endpoint
`type`	string	Filtrar por tipo de evento (ej: `invoice.created`)
`status`	string	Filtrar por estado (`pending`, `delivered`, `failed`, `disabled`)
`limit`	number	Máximo de resultados por página (hasta 100)
`cursor`	string	Cursor para la siguiente página de resultados

Estados de un evento

Estado	Descripción
`pending`	Evento creado, pendiente de entrega
`delivered`	Entregado con éxito (respuesta HTTP 2xx)
`failed`	Todos los reintentos agotados o error permanente
`disabled`	El endpoint estaba desactivado en el momento del intento

Errores comunes

Error 403: Forbidden

Tu clave de API no tiene los permisos necesarios. Verifica que la clave incluye los scopes webhooks:read y/o webhooks:write según la operación.

Error 422: Unprocessable Entity

Los datos enviados no son válidos. Causas habituales:

La URL no empieza por https://
La URL apunta a una IP privada (localhost, 127.x, 10.x, 192.168.x)
No se ha seleccionado ningún evento
El tipo de evento no existe en el catálogo

Error 404: Not Found

El endpoint o evento no existe. Verifica que el ID es correcto y pertenece a tu empresa.

API: Webhooks (endpoints y eventos)