> ## Documentation Index > Fetch the complete documentation index at: https://docs.quentli.com/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks > Recibe notificaciones HTTP sobre eventos de cobros, clientes y suscripciones. Los webhooks notifican a tu servidor cuando ocurre un evento relevante en Quentli. Cada entrega es una solicitud HTTP `POST` con un cuerpo JSON UTF-8 y el siguiente sobre: ```json theme={null} { "eventId": "wev_1234567890", "eventType": "PAYMENT_ATTEMPT_SUCCEEDED", "data": {} } ``` `eventId` identifica una entrega. Guarda y deduplica este valor: el mismo evento se puede entregar más de una vez. ## Configura un webhook Crea un endpoint HTTPS desde `POST /v1/webhooks`. Define solamente los eventos que tu integración procesa. ```json POST /v1/webhooks theme={null} { "input": { "url": "https://miapp.com/webhooks/quentli", "description": "Sincronización de cobros", "enabledEvents": ["INVOICE_PAID", "PAYMENT_ATTEMPT_SUCCEEDED", "PAYMENT_ATTEMPT_FAILED"] } } ``` ## Entrega y reintentos * Responde `2xx` en menos de 10 segundos para confirmar la entrega. * Las respuestas no `2xx`, timeouts y errores de conexión se reintentan hasta ocho veces, después del primer intento. * Los reintentos se programan después de 2 segundos, 10 segundos, 5 minutos, 20 minutos, 1 hora, 5 horas, 1 día y 3 días. * No asumas orden entre eventos. Usa `eventId` para deduplicar y consulta el estado actual del recurso si recibes eventos fuera de orden. * Puedes consultar el historial en `GET /v1/webhook-events` y reintentar una entrega con `POST /v1/webhook-events/{id}/retry`. ## Eventos disponibles | Evento | Se envía cuando | | --------------------------- | ------------------------------------------------------------- | | `INVOICE_CREATED` | Se crea una solicitud de pago. | | `INVOICE_UPDATED` | Se actualiza una solicitud de pago. | | `INVOICE_CANCELED` | Se cancela una solicitud de pago. | | `INVOICE_PAID` | Se liquida una solicitud mediante Quentli o su total es cero. | | `INVOICE_PAID_OTHER` | Se registra un pago recibido fuera de Quentli. | | `CUSTOMER_CREATED` | Se crea un cliente. | | `CUSTOMER_UPDATED` | Se actualiza un cliente. | | `CUSTOMER_ARCHIVED` | Se archiva un cliente. | | `PAYMENT_ATTEMPT_SUCCEEDED` | Un intento de cobro termina correctamente. | | `PAYMENT_ATTEMPT_FAILED` | Un intento de cobro es rechazado o falla. | | `PAYMENT_COMPLETED` | Un pago termina de procesarse. | | `PAYMENT_METHOD_CREATED` | Un cliente guarda un método de pago. | | `PAYMENT_REFUNDED` | Se actualiza un reembolso de un pago. | | `DISPUTE_CREATED` | Se crea un contracargo. | | `DISPUTE_RESPONSE_CREATED` | Se registra una respuesta a un contracargo. | | `DISPUTE_RESOLVED` | Se resuelve un contracargo. | | `SUBSCRIPTION_CREATED` | Se crea una suscripción. | | `SUBSCRIPTION_UPDATED` | Se actualiza una suscripción. | | `SUBSCRIPTION_CANCELED` | Se cancela una suscripción. | ## Estructura de `data` Los payloads incluyen todos los campos descritos a continuación. Los objetos y campos marcados como opcionales pueden ser `null` o no estar presentes según el evento y el método de pago. | Eventos | Campos principales de `data` | | ---------------- | -------------------------------------------------------------------------------------------------------------------- | | Facturas | `invoiceId`, `description`, `amount`, `invoice`, `payment?`, `customer?`, `organization`, `metadata`, `formAnswers?` | | Clientes | `id`, `name`, `email`, `phoneNumber`, `username`, `metadata` | | Intentos de pago | `payment`, `paymentAttempt`, `customer`, `paymentSession` | | Pago completado | `payment`, `items`, `relatedInvoices`, `paymentAttempt?`, `customer`, `paymentSession?` | | Método de pago | `paymentMethod`, `customer` | | Reembolsos | `refund`, `payment`, `customer`, `organization` | | Contracargos | `dispute`, `response`, `payment`, `customer`, `organization` | | Suscripciones | `subscription`, `customer`, `organization` | ### Facturas `invoice` contiene `id`, `amount`, `currency`, `dueDate`, `expireDate` e `items`. Cada item incluye `description`, `amount`, `currency`, `quantity` y `conceptId`. Cuando existe un pago, `payment` incluye su identificador, monto, moneda, fecha de pago, tipo, código de autorización y detalles de tarjeta cuando corresponde. ### Intentos y pagos Los eventos de intento incluyen `payment.status`, `payment.isCompleted`, `payment.meta` y `paymentAttempt` con `id`, `createdAt`, `success`, `startedOn`, `automatic`, `scheduled`, `wasAttemptedByOrganization`, `attemptNumber`, `errorCode`, `errorType` y `errorResponse`. Los detalles de tarjeta y la sesión de pago pueden ser `null`. `PAYMENT_COMPLETED` incluye los items cobrados y las facturas relacionadas. Su `paymentAttempt` es `null` cuando no existe un intento asociado. ### Métodos de pago `paymentMethod` contiene `id`, `type`, `confirmed`, `chargesConsented`, `cardDetail` y `bankAccount`. Los detalles de tarjeta o cuenta bancaria son `null` cuando no aplican. `customer` incluye sus identificadores, datos de contacto y metadatos. ### Suscripciones, reembolsos y contracargos Las suscripciones contienen sus fechas de cobro, estado, método de cobranza, items y el cliente asociado. Los reembolsos incluyen su estado, monto, fechas y pago original. Los contracargos incluyen estado, motivo, fecha límite de respuesta, respuesta asociada y pago original. ## Ejemplo: método de pago creado ```json theme={null} { "eventId": "wev_1234567890", "eventType": "PAYMENT_METHOD_CREATED", "data": { "paymentMethod": { "id": "pm_1234567890", "type": "CARD", "confirmed": true, "chargesConsented": true, "cardDetail": { "id": "card_1234567890", "cardholder": "Ana Rodriguez", "last4": "4242", "brand": "VISA", "expiryMonth": 12, "expiryYear": 2028, "funding": "DEBIT", "issuer": "BBVA", "country": "MEX" }, "bankAccount": null }, "customer": { "id": "cus_1234567890", "name": "Ana Rodriguez", "email": "ana@example.com", "phoneNumber": "+525555123456", "username": "cliente-123", "metadata": [], "meta": {} } } } ```