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

# Enviar webhooks para o seu próprio sistema

> A integração Webhooks envia um evento JSON assinado para o seu próprio endpoint quando o Foliant gera um documento ou conclui uma exportação.

A integração **Webhooks** é para desenvolvedores. Ela envia um evento JSON para um endereço HTTPS que você escolhe sempre que algo acontece no Foliant. Assim, o seu próprio sistema pode reagir, por exemplo, arquivando o PDF de cada fatura ou buscando uma exportação concluída.

A integração Webhooks está em beta. Se você não a encontrar em **Configurações › Integrações**, ela ainda não está disponível para a sua loja. Entre em contato com o suporte para pedir acesso.

## Eventos

| Evento | Enviado quando |
| - | - |
| `document.generated` (**Documento gerado**) | O Foliant cria um documento para um pedido: um download, uma exportação ou um e-mail com o PDF. |
| `export.completed` (**Exportação concluída**) | Uma exportação em massa está pronta. |

## Conectar webhooks

1. No Foliant, acesse **Configurações › Integrações**.

2. Em **Webhooks**, clique em **Conectar**.

3. Preencha as configurações:

   | Campo | O que informar |
   | - | - |
   | **URL do endpoint** | O endereço para onde o Foliant envia os eventos. Ele precisa usar HTTPS, como `https://example.com/webhooks/foliant`. |
   | **Segredo de assinatura** | Opcional. Com um segredo, cada solicitação é assinada para que você possa confirmar que ela veio do Foliant. |
   | **Eventos** | Os eventos a serem enviados. Os dois vêm selecionados por padrão. |

4. Clique em **Conectar**.

Você pode alterar a URL, o segredo e os eventos depois, em **Configurações** na página da integração.

## O que cada solicitação contém

O Foliant envia uma solicitação `POST` com um 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": { }
}
```

### Dados de `document.generated`

* `template`: o `uuid` e o `name` do modelo.
* `document_type`: `invoice`, `credit_note`, `quote` ou vazio para outros documentos.
* `order`: o `id`, o `name` e o `type` do pedido (pedidos ou pedidos preliminares).
* `refund_id` e `fulfillment_id`, quando o documento é de um reembolso ou de um envio.
* `document_number` e `issued_at`, para documentos numerados.
* `source`: como ele foi gerado, como `download`, `admin_download`, `export` ou `email`.
* `export`: o ID da exportação, quando ele faz parte de uma exportação.
* `generated_at`.

### Dados de `export.completed`

* `export`: o `uuid`, o `order_type`, os `template_uuids`, o número de `orders`, os `orders_skipped` (excluídos depois de terem sido escolhidos) e os `documents`, o `requested_by` (`merchant` ou `customer`) e o `completed_at`.
* `download_url`: um link para baixar a exportação, e `download_url_expires_at`, quando esse link deixa de funcionar.
* `download_expires_at`: quando a própria exportação expira.

Os eventos contêm IDs e contagens, não endereços de e-mail de clientes.

### Cabeçalhos

| Cabeçalho | Contém |
| - | - |
| `X-Foliant-Event` | O evento, como `document.generated`. |
| `X-Foliant-Delivery` | O ID exclusivo da entrega (o mesmo que `id` no corpo). |
| `X-Foliant-Timestamp` | Quando foi enviado, em segundos Unix. |
| `X-Foliant-Signature` | `sha256=` seguido da assinatura. Somente quando você define um segredo de assinatura. |

## Verificar a assinatura

A assinatura é um HMAC-SHA256 em hexadecimal do timestamp, de um ponto final e do corpo bruto da solicitação (`<timestamp>.<body>`), usando o seu segredo de assinatura como chave. Calcule-a do seu lado e compare com o valor depois de `sha256=` em `X-Foliant-Signature`. Use o corpo bruto exatamente como foi recebido.

## Respostas e novas tentativas

* Qualquer resposta 2xx conta como entregue.
* Se o seu endpoint retornar um erro 5xx, 408 ou 429, ou não responder em 10 segundos, o Foliant tenta de novo mais tarde, esperando mais a cada vez, até 5 tentativas.
* Outras respostas 4xx são definitivas: o Foliant não tenta de novo.
* Cada evento é entregue uma vez por documento ou exportação. As novas tentativas nunca o enviam duas vezes depois de um sucesso.

Todas as entregas aparecem em **Atividade** na página da integração, onde você pode clicar em **Tentar novamente** em uma entrega que falhou. Veja [Atividade da integração](https://foliant-help.iforiti.com/pt-BR/integrations/integration-activity.md).

## Artigos relacionados

* [Conectar e gerenciar uma integração](https://foliant-help.iforiti.com/pt-BR/integrations/connect-an-integration.md)
* [Atividade da integração](https://foliant-help.iforiti.com/pt-BR/integrations/integration-activity.md)
* [Automatizar com o Shopify Flow](https://foliant-help.iforiti.com/pt-BR/integrations/shopify-flow.md)
* [Exportar PDFs](https://foliant-help.iforiti.com/pt-BR/exports/export-pdfs.md)


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