> ## 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.

# Invia webhook al tuo sistema

> L'integrazione Webhook invia un evento JSON firmato al tuo endpoint quando Foliant genera un documento o completa un'esportazione.

L'integrazione **Webhooks** è pensata per gli sviluppatori. Invia un evento JSON a un indirizzo HTTPS che scegli tu ogni volta che succede qualcosa in Foliant, così il tuo sistema può reagire, ad esempio archiviando il PDF di ogni fattura o recuperando un'esportazione completata.

Webhooks è in beta. Se non lo vedi in **Impostazioni › Integrazioni**, non è ancora disponibile per il tuo negozio. Contatta l'assistenza per chiedere l'accesso.

## Eventi

| Evento | Inviato quando |
| - | - |
| `document.generated` (**Document generated**) | Foliant crea un documento per un ordine: un download, un'esportazione o un'email di invio del PDF. |
| `export.completed` (**Export completed**) | Un'esportazione in blocco è pronta. |

## Collega i webhook

1. In Foliant, vai su **Impostazioni › Integrazioni**.

2. Su **Webhooks**, fai clic su **Collega**.

3. Compila le impostazioni:

   | Campo | Cosa inserire |
   | - | - |
   | **Endpoint URL** | L'indirizzo a cui Foliant invia gli eventi. Deve usare HTTPS, ad esempio `https://example.com/webhooks/foliant`. |
   | **Signing secret** | Facoltativo. Con un secret, ogni richiesta viene firmata, così puoi verificare che provenga da Foliant. |
   | **Events** | Gli eventi da inviare. Per impostazione predefinita sono selezionati entrambi. |

4. Fai clic su **Collega**.

Puoi modificare l'URL, il secret e gli eventi in seguito in **Impostazioni** nella pagina dell'integrazione.

## Cosa contiene ogni richiesta

Foliant invia una richiesta `POST` con un corpo 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": { }
}
```

### Dati di `document.generated`

* `template`: `uuid` e `name` del modello.
* `document_type`: `invoice`, `credit_note`, `quote` oppure vuoto per gli altri documenti.
* `order`: i suoi `id`, `name` e `type` (ordini o bozze di ordini).
* `refund_id` e `fulfillment_id`, quando il documento riguarda un rimborso o una spedizione.
* `document_number` e `issued_at`, per i documenti numerati.
* `source`: come è stato creato, ad esempio `download`, `admin_download`, `export` o `email`.
* `export`: l'ID dell'esportazione, quando fa parte di un'esportazione.
* `generated_at`.

### Dati di `export.completed`

* `export`: i suoi `uuid`, `order_type`, `template_uuids`, il numero di `orders`, `orders_skipped` (eliminati dopo essere stati scelti) e `documents`, `requested_by` (`merchant` o `customer`) e `completed_at`.
* `download_url`: un link per scaricare l'esportazione, e `download_url_expires_at`, quando quel link smette di funzionare.
* `download_expires_at`: quando scade l'esportazione stessa.

Gli eventi contengono ID e conteggi, non indirizzi email dei clienti.

### Header

| Header | Contiene |
| - | - |
| `X-Foliant-Event` | L'evento, ad esempio `document.generated`. |
| `X-Foliant-Delivery` | L'ID univoco dell'invio (lo stesso di `id` nel corpo). |
| `X-Foliant-Timestamp` | Quando è stato inviato, in secondi Unix. |
| `X-Foliant-Signature` | `sha256=` seguito dalla firma. Solo se hai impostato un signing secret. |

## Verifica la firma

La firma è un HMAC-SHA256 esadecimale del timestamp, di un punto e del corpo grezzo della richiesta (`<timestamp>.<body>`), con il tuo signing secret come chiave. Calcolala dal tuo lato e confrontala con il valore dopo `sha256=` in `X-Foliant-Signature`. Usa il corpo grezzo esattamente come lo hai ricevuto.

## Risposte e nuovi tentativi

* Qualsiasi risposta 2xx vale come consegnata.
* Se il tuo endpoint restituisce un errore 5xx, 408 o 429, oppure non risponde entro 10 secondi, Foliant riprova più tardi, aspettando ogni volta più a lungo, fino a 5 tentativi.
* Le altre risposte 4xx sono definitive: Foliant non riprova.
* Ogni evento viene consegnato una sola volta per documento o esportazione. I nuovi tentativi non lo inviano mai due volte dopo un successo.

Ogni invio compare in **Attività** nella pagina dell'integrazione, dove puoi fare clic su **Riprova** per quelli non riusciti. Vedi [Attività dell'integrazione](https://foliant-help.iforiti.com/it/integrations/integration-activity.md).

## Articoli correlati

* [Collegare e gestire un'integrazione](https://foliant-help.iforiti.com/it/integrations/connect-an-integration.md)
* [Attività dell'integrazione](https://foliant-help.iforiti.com/it/integrations/integration-activity.md)
* [Automatizzare con Shopify Flow](https://foliant-help.iforiti.com/it/integrations/shopify-flow.md)
* [Esportare PDF](https://foliant-help.iforiti.com/it/exports/export-pdfs.md)


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