> ## Documentation Index
> Fetch the complete documentation index at: https://foliant-help.iforiti.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Envía webhooks a tu propio sistema

> La integración Webhooks envía un evento JSON firmado a tu propio endpoint cuando Foliant genera un documento o termina una exportación.

La integración **Webhooks** está pensada para desarrolladores. Envía un evento JSON a una dirección HTTPS que tú eliges cada vez que ocurre algo en Foliant, para que tu propio sistema pueda reaccionar, por ejemplo, archivando el PDF de cada factura o recogiendo una exportación terminada.

Webhooks está en beta. Si no la ves en **Configuración › Integraciones**, todavía no está disponible para tu tienda. Contacta con soporte para pedir acceso.

## Eventos

| Evento | Se envía cuando |
| - | - |
| `document.generated` (**Documento generado**) | Foliant crea un documento para un pedido: una descarga, una exportación o un correo de entrega de PDF. |
| `export.completed` (**Exportación completada**) | Una exportación masiva está lista. |

## Conecta los webhooks

1. En Foliant, ve a **Configuración › Integraciones**.

2. En **Webhooks**, haz clic en **Conectar**.

3. Completa la configuración:

   | Campo | Qué introducir |
   | - | - |
   | **URL del endpoint** | La dirección a la que Foliant envía los eventos. Debe usar HTTPS, como `https://example.com/webhooks/foliant`. |
   | **Secreto de firma** | Opcional. Con un secreto, cada solicitud se firma para que puedas comprobar que viene de Foliant. |
   | **Eventos** | Los eventos que se envían. Ambos están seleccionados de forma predeterminada. |

4. Haz clic en **Conectar**.

Puedes cambiar la URL, el secreto y los eventos más adelante en **Configuración**, en la página de la integración.

## Qué contiene cada solicitud

Foliant envía una solicitud `POST` con un cuerpo JSON:

```json theme={null}
{
  "id": "a unique delivery id",
  "event": "document.generated",
  "created_at": "2026-10-11T09:30:00+00:00",
  "shop": "your-store.myshopify.com",
  "data": { }
}
```

### Datos de `document.generated`

* `template`: el `uuid` y el `name` de la plantilla.
* `document_type`: `invoice`, `credit_note`, `quote`, o vacío para otros documentos.
* `order`: su `id`, `name` y `type` (pedidos o borradores de pedidos).
* `refund_id` y `fulfillment_id`, cuando el documento corresponde a un reembolso o a un envío.
* `document_number` y `issued_at`, para documentos numerados.
* `source`: cómo se generó, como `download`, `admin_download`, `export` o `email`.
* `export`: el ID de la exportación, cuando forma parte de una exportación.
* `generated_at`.

### Datos de `export.completed`

* `export`: su `uuid`, `order_type`, `template_uuids`, el número de `orders`, `orders_skipped` (eliminados después de seleccionarlos) y `documents`, `requested_by` (`merchant` o `customer`) y `completed_at`.
* `download_url`: un enlace para descargar la exportación, y `download_url_expires_at`, cuándo deja de funcionar ese enlace.
* `download_expires_at`: cuándo caduca la propia exportación.

Los eventos contienen IDs y recuentos, no direcciones de correo electrónico de clientes.

### Encabezados

| Encabezado | Contiene |
| - | - |
| `X-Foliant-Event` | El evento, como `document.generated`. |
| `X-Foliant-Delivery` | El ID único de la entrega (el mismo que `id` en el cuerpo). |
| `X-Foliant-Timestamp` | Cuándo se envió, en segundos Unix. |
| `X-Foliant-Signature` | `sha256=` seguido de la firma. Solo cuando configuras un secreto de firma. |

## Comprueba la firma

La firma es un HMAC-SHA256 en hexadecimal de la marca de tiempo, un punto y el cuerpo sin procesar de la solicitud (`<timestamp>.<body>`), usando tu secreto de firma como clave. Calcúlala por tu parte y compárala con el valor que sigue a `sha256=` en `X-Foliant-Signature`. Usa el cuerpo sin procesar exactamente como lo recibes.

## Respuestas y reintentos

* Cualquier respuesta 2xx cuenta como entregada.
* Si tu endpoint devuelve un error 5xx, 408 o 429, o no responde en 10 segundos, Foliant vuelve a intentarlo más tarde, esperando más cada vez, hasta 5 intentos.
* Las demás respuestas 4xx son definitivas: Foliant no las reintenta.
* Cada evento se entrega una vez por documento o exportación. Los reintentos nunca lo envían dos veces después de una entrega correcta.

Cada entrega aparece en **Actividad**, en la página de la integración, donde puedes usar **Reintentar** en una que haya fallado. Consulta [Actividad de la integración](https://foliant-help.iforiti.com/es/integrations/integration-activity.md).

## Artículos relacionados

* [Conecta y gestiona una integración](https://foliant-help.iforiti.com/es/integrations/connect-an-integration.md)
* [Actividad de la integración](https://foliant-help.iforiti.com/es/integrations/integration-activity.md)
* [Automatiza con Shopify Flow](https://foliant-help.iforiti.com/es/integrations/shopify-flow.md)
* [Exporta PDF](https://foliant-help.iforiti.com/es/exports/export-pdfs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.