Factuarea API
Webhooks

Hacer ping al webhook endpoint

Envía un evento de prueba (`webhook.ping`) al endpoint para verificar que es accesible y que el handshake de firma funciona. La entrega sintética aparece en `GET /webhook_endpoints/{webhook_endpoint}/deliveries`.

POST
/webhook_endpoints/{webhook_endpoint}/ping

Authorization

AuthorizationBearer <token>

En: header

Parámetros de ruta

webhook_endpoint*string

Parámetros de cabecera

Idempotency-Key?string

Clave única generada por el cliente para garantizar la idempotencia en los reintentos. Te permite reenviar de forma segura la misma petición: la primera respuesta se cachea y se devuelve sin volver a ejecutar la mutación. Es una cadena opaca para el servidor; cualquier valor único de hasta 64 caracteres es válido (UUID v7, UUID v4, ULID, nanoid, etc.). Se recomienda UUID v7 por coherencia con los identificadores de la API. La misma clave reutilizada con un body distinto devuelve 409 idempotency_key_reused.

Longitud1 <= length <= 64

Cuerpo de la respuesta

application/json

application/json

application/json

application/json

application/json

{
  "data": {
    "success": false,
    "http_status": 503,
    "response_body": "<html><body>503 Service Unavailable</body></html>",
    "error_message": "El endpoint respondió con un código de estado no-2xx (503).",
    "duration_ms": 87
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se ha proporcionado una API key válida en el header Authorization.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido para esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
  }
}

Listar todos los webhook endpoints

Lista tus webhook endpoints con paginación por cursor.

Rota el secreto del webhook

Rota el secreto de firma de un webhook endpoint. El nuevo secreto se devuelve **una sola vez** en esta respuesta. El secreto anterior sigue siendo válido durante un periodo de gracia de 24 horas (ver `previous_secret_valid_until`) para permitir una rotación sin tiempo de inactividad.