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

# Webhooks

> Envie eventos externos para o Portal disparar automações

# Webhooks

Webhooks são o caminho mais simples para **um sistema externo disparar uma reação no Portal**. Você cria uma automação com gatilho Webhook, o Portal te entrega um `webhook_id`, e seu sistema faz um `POST` quando algo acontecer.

## Quando usar webhook?

* Seu sistema (CRM, ERP, monitoramento, IFTTT, n8n, Zapier) precisa **acionar dispositivos** no Portal a partir de um evento dele.
* Você não quer gerenciar token (o `webhook_id` já e o segredo).
* A ação final e simples: ligar/desligar algo, mandar notificação, executar script.

Se você precisa de fluxo bidirecional (ler estado + agir), use [PAT + chamada de serviço](/integrador/controlando-entidades).

## Configurando o webhook

<Steps>
  <Step title="Crie uma automação">
    No painel, va em **Automações → Nova Automação**.
  </Step>

  <Step title="Gatilho Webhook">
    Escolha **Gatilho → Webhook**. O Portal gera um `webhook_id` (uma string aleatoria longa).
  </Step>

  <Step title="Defina as ações">
    Adicione as ações que devem rodar quando o webhook for chamado.
  </Step>

  <Step title="Copie a URL">
    A URL final e:

    ```
    https://portal.unicontrol.me/v1/automations/webhook/{webhook_id}
    ```
  </Step>
</Steps>

## Chamando o webhook

```bash theme={null}
curl -X POST https://portal.unicontrol.me/v1/automations/webhook/abc123xyz \
  -H "Content-Type: application/json" \
  -d '{
    "evento": "porta_aberta",
    "local": "garagem",
    "timestamp": "2026-05-28T14:00:00-03:00"
  }'
```

<Info>
  Webhooks **não** exigem header `Authorization`. O próprio `webhook_id` na URL e o segredo.
</Info>

A resposta padrão e `200 OK` com corpo vazio. Erros possíveis: `404` (webhook não existe ou foi revogado).

## Usando o payload nas ações

O body JSON enviado fica disponível nas ações da automação via templates. Exemplos:

| Template                    | Resultado      |
| --------------------------- | -------------- |
| `{{ trigger.json.evento }}` | `porta_aberta` |
| `{{ trigger.json.local }}`  | `garagem`      |

Você pode usar isso, por exemplo, para enviar uma notificação dinâmica:

```
Acao: Notificacao
Mensagem: "Porta aberta em {{ trigger.json.local }}"
```

## Boas práticas

* **Rotacione webhooks comprometidos**: se desconfiar de vazamento, exclua a automação e recrie com novo `webhook_id`.
* **Valide o payload**: a automação pode começar com uma condição verificando campos esperados.
* **Não exponha em frontend público**: o `webhook_id` na mao errada permite acionar ações na sua casa. Use webhook apenas em sistemas controlados (backend-to-backend, n8n self-hosted, etc.).
* **Idempotencia**: se o seu sistema externo pode retry, deixe a automação tolerante a chamadas duplicadas (ex: não adicione duas vezes o mesmo item).

## Webhooks no caminho contrario (Portal → seu sistema)

Para o Portal **enviar** dados pro seu sistema quando algo acontece, use uma automação com:

* Gatilho: o evento que quer monitorar (mudança de estado, horário, etc.)
* Ação: **Chamar URL** (HTTP request) apontando pro seu endpoint

```
Acao: Chamar URL
Metodo: POST
URL: https://meu-servico.exemplo.com/portal-hook
Body: { "entity_id": "{{ trigger.entity_id }}", "state": "{{ trigger.to_state.state }}" }
```

Adicione header `Authorization` na própria configuração da ação se seu endpoint exige autenticação.