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

# Webhooks

> Inscreva sistemas externos nos eventos—WhatsApp, iMessage e SMS de entrada/saída, e eventos do sistema.

Os webhooks permitem enviar eventos em tempo real para qualquer endpoint externo. Use-os para sincronizar mensagens com seu CRM, acionar automações no n8n/Make/Zapier ou construir backends personalizados.

## Criar uma Assinatura de Webhook

<Steps>
  <Step title="Abra sua Location">
    Vá para **Dashboard → Locations** e selecione a location que você deseja inscrever.
  </Step>

  <Step title="Abra as Configurações">
    Clique na aba **Settings** (Configurações) dessa location.
  </Step>

  <Step title="Criar assinatura">
    Role até a seção **Webhooks** e clique em **Create subscription** (Criar assinatura).
  </Step>

  <Step title="Preencha o formulário">
    Complete o diálogo **Create subscription** (veja os campos abaixo).
  </Step>

  <Step title="Salvar">
    Clique em **Create subscription** para salvar. Se "Enviar um ping de teste" estiver ativado, um evento fictício será enviado via POST ao seu endpoint para verificar se ele funciona.
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/goghl/JZJa2MoUHOf9Nw9w/images/features/assets/images/webhook.png?fit=max&auto=format&n=JZJa2MoUHOf9Nw9w&q=85&s=c08867acc50c1e7f8c94f0c4841ffdf2" alt="Criar assinatura de webhook" width="2886" height="1862" data-path="images/features/assets/images/webhook.png" />
</Frame>

## Campos da Assinatura

### Nome *(obrigatório)*

Um rótulo legível para que você possa identificar a assinatura depois (ex.: `Sincronização CRM`, `Handler de Entrada n8n`).

### URL de Destino

O endpoint HTTPS que receberá os payloads dos eventos.

```text theme={null}
https://example.com/webhooks
```

<Note>
  Seu endpoint deve responder com um código de status `2xx`. Respostas que não sejam 2xx são tratadas como falhas.
</Note>

### Selecionar eventos

Escolha exatamente quais eventos devem acionar um webhook. Você pode combinar canais em uma única assinatura.

#### WhatsApp

* **Inbound (Entrada)** — uma mensagem de WhatsApp é recebida
* **Outbound (Saída)** — uma mensagem de WhatsApp é enviada

#### iMessage

* **Inbound (Entrada)** — um iMessage é recebido
* **Outbound (Saída)** — um iMessage é enviado

#### SMS

* **Inbound (Entrada)** — um SMS é recebido
* **Outbound (Saída)** — um SMS é enviado

#### Sistema

* **Message failed (Falha na mensagem)** — uma mensagem não pôde ser entregue (use para lógica de novas tentativas ou alertas)

### Enviar um ping de teste após a criação

Quando ativado, o sistema enviará via POST um evento fictício para sua **URL de Destino** imediatamente após a criação da assinatura. Use isso para confirmar que seu endpoint está acessível e que seu handler interpreta os payloads corretamente.

<Tip>
  Deixe esta opção **ativada** na primeira assinatura que você criar para um novo endpoint.
</Tip>

## Boas Práticas

* **Use uma assinatura por integração.** Mantém os logs e a rotação simples.
* **Verifique com o ping de teste** antes de confiar em uma assinatura em produção.
* **Retorne `2xx` rapidamente** — delegue o trabalho lento a uma fila em segundo plano no seu handler.
* **Seja idempotente.** Webhooks podem ocasionalmente ser reentregues.
* **Delimite por canal.** Não se inscreva em eventos que você não vai processar.

## Gerenciando Assinaturas

Na seção **Webhooks** das Configurações da Location, você pode:

* Ver todas as assinaturas ativas e a data de criação
* Excluir uma assinatura de que você não precisa mais
* Criar assinaturas adicionais para endpoints separados

## Solução de Problemas

<AccordionGroup>
  <Accordion title="O ping de teste nunca chegou">
    * Confirme que seu endpoint está acessível publicamente (sem localhost / IPs privados)
    * Verifique se ele aceita `POST` e retorna `2xx`
    * Confira se regras de firewall/WAF não estão bloqueando o IP
  </Accordion>

  <Accordion title="Os eventos pararam de disparar">
    * Certifique-se de que a assinatura não foi excluída
    * Confirme que a location ainda tem uma instância conectada para o canal
    * Verifique os logs do seu endpoint em busca de respostas `5xx` (falhas repetidas podem desativar a entrega)
  </Accordion>

  <Accordion title="Eventos duplicados">
    Os webhooks têm entrega "pelo menos uma vez" (at-least-once). Use o ID do evento no payload para deduplicar do seu lado.
  </Accordion>
</AccordionGroup>