> ## 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** destina-se a programadores. Envia um evento JSON para um endereço HTTPS à sua escolha sempre que algo acontece no Foliant, para que o seu próprio sistema possa reagir, por exemplo, arquivando o PDF de cada fatura ou recolhendo uma exportação concluída.

A integração Webhooks está em beta. Se não a vir em **Definições › Integrações**, ainda não está disponível para a sua loja. Contacte o suporte para pedir acesso.

## Eventos

| Evento | Enviado quando |
| - | - |
| `document.generated` (**Documento gerado**) | O Foliant cria um documento para uma encomenda: uma transferência, uma exportação ou um email de entrega de PDF. |
| `export.completed` (**Exportação concluída**) | Uma exportação em massa está pronta. |

## Ligar os webhooks

1. No Foliant, aceda a **Definições › Integrações**.

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

3. Preencha as definições:

   | Campo | O que introduzir |
   | - | - |
   | **URL do endpoint** | O endereço para onde o Foliant envia os eventos. Tem de usar HTTPS, como `https://example.com/webhooks/foliant`. |
   | **Segredo de assinatura** | Opcional. Com um segredo, cada pedido é assinado para que possa confirmar que veio do Foliant. |
   | **Eventos** | Os eventos a enviar. Ambos estão selecionados por predefinição. |

4. Clique em **Ligar**.

Pode alterar o URL, o segredo e os eventos mais tarde em **Definições**, na página da integração.

## O que cada pedido contém

O Foliant envia um pedido `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 respetivo `id`, `name` e `type` (encomendas ou encomendas de rascunho).
* `refund_id` e `fulfillment_id`, quando o documento se refere a um reembolso ou a um envio.
* `document_number` e `issued_at`, para documentos numerados.
* `source`: como foi criado, como `download`, `admin_download`, `export` ou `email`.
* `export`: o ID da exportação, quando faz parte de uma exportação.
* `generated_at`.

### Dados de `export.completed`

* `export`: o respetivo `uuid`, `order_type`, `template_uuids`, número de `orders`, `orders_skipped` (eliminadas depois de terem sido escolhidas) e `documents`, `requested_by` (`merchant` ou `customer`) e `completed_at`.
* `download_url`: uma ligação para transferir a exportação, e `download_url_expires_at`, quando essa ligação 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 email de clientes.

### Cabeçalhos

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

## Verificar a assinatura

A assinatura é um HMAC-SHA256 em hexadecimal do timestamp, um ponto final e o corpo bruto do pedido (`<timestamp>.<body>`), usando o seu segredo de assinatura como chave. Calcule-a do seu lado e compare-a com o valor a seguir a `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 devolver um erro 5xx, 408 ou 429, ou não responder em 10 segundos, o Foliant tenta novamente mais tarde, esperando mais tempo de cada vez, até 5 tentativas.
* As outras respostas 4xx são definitivas: o Foliant não volta a tentar.
* Cada evento é entregue uma vez por documento ou exportação. As novas tentativas nunca o enviam duas vezes depois de um sucesso.

Cada entrega aparece em **Atividade**, na página da integração, onde pode clicar em **Tentar novamente** numa entrega falhada. Consulte [Atividade da integração](https://foliant-help.iforiti.com/pt-PT/integrations/integration-activity.md).

## Artigos relacionados

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


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