## O que o webhook envia

Um webhook é um endereço do seu lado para o qual o BulkGate comunica o que aconteceu
às suas mensagens. O portal chama-lhe `Relatórios de entrega`, mas envia-lhe duas coisas
em simultâneo:

| O que chega | Como o reconhece |
|:--|:--|
| Relatório de entrega | Um registo com o estado de uma mensagem enviada e o respetivo `smsID` |
| SMS recebida (uma resposta) | Um registo com `status` `10`, o remetente em `from` e o texto da mensagem |

Não se trata, portanto, de duas definições separadas — um único endereço trata tanto dos
relatórios de entrega como das respostas.

O formato dos dados depende de o envio em massa estar ou não ativado:

| Modo | Como chegam os dados | Formato descrito em |
|:--|:--|:--|
| predefinido | Um pedido por mensagem, por GET | [Confirmações de entrega](https://www.bulkgate.com/pt/documentacao/administracao-da-api/api-confirmacoes-de-entrega-e-sms-recebidos/) |
| `DLRs em massa - solicitação em massa` | Um lote de registos, por POST com `application/json` | [Confirmações de entrega em massa](https://www.bulkgate.com/pt/documentacao/administracao-da-api/api-confirmacoes-de-entrega-em-massa-e-mensagens-recebidas/) |

## Onde se define o webhook

O local depende da interface que utiliza. Os dois primeiros passos são iguais em
todos os casos — clique em `Módulos e APIs` no menu do portal e abra o cartão da sua
aplicação em `Minhas APIs e módulos`.

| Interface | Onde no detalhe da aplicação |
|:--|:--|
| HTTP API | O separador `Definições`, a parte `Web hooks`, o cartão `Relatórios de entrega` |
| `Email > SMS` | Apenas `Relatórios de entrega de e-mail` — os relatórios chegam por e-mail, não para um URL |

## Como ativar o webhook

O cartão mostra se há algo definido. Enquanto nada estiver definido, mostra
`Você não tem configurações.` e um botão `Configurar`.

![A parte Web hooks com o cartão Relatórios de entrega](docs:api-webhooks/webhooks_en)

O botão `Configurar` (ou `Editar`, se já tiver definições) abre a janela
`Configuração de relatórios de entrega`.

![A janela Configuração de relatórios de entrega com o campo Relatórios de entrega de URL](docs:api-webhooks/delivery-report_en)

Introduza um endereço que comece por `http://` ou `https://` no campo `Relatórios de entrega
de URL` — o portal não aceita outra forma de escrita. A ele associam-se três caixas de
verificação:

| Opção | O que faz |
|:--|:--|
| `Desative a verificação de disponibilidade de URL` | O portal não verifica se o endereço responde antes de guardar |
| `Reportar apenas quando ocorrer erro` | Um relatório chega apenas para uma mensagem que falhou |
| `DLRs em massa - solicitação em massa` | Os relatórios chegam em lotes em vez de um a um |

Guarda a configuração com o botão `Salve`.

> [!TIP]
> O envio em massa é útil em volumes elevados — em vez de um pedido por mensagem,
> chega um único pedido com uma matriz de registos. O formato do lote está descrito
> em [Confirmações de entrega em massa](https://www.bulkgate.com/pt/documentacao/administracao-da-api/api-confirmacoes-de-entrega-em-massa-e-mensagens-recebidas/).

Depois de definido o webhook, o cartão apresenta três linhas — `URL` com o endereço e
um ícone para cada uma das opções `Reportar apenas quando ocorrer erro` e `DLRs em massa - solicitação em massa`,
que indica se estão ativadas.

## Como remover o webhook

A seta junto ao botão `Editar` abre um menu com a opção `Excluir`. A
janela de confirmação `Excluir configurações` avisa que perderá as definições dos
relatórios de entrega e que estes deixarão de chegar.

> [!WARNING]
> Remover o webhook interrompe também as mensagens recebidas — as respostas às suas SMS
> deixam de ter para onde ser entregues.