---
title: "Webhook de entrada"
slug: inbound-webhook
group: "Webhooks"
source: https://linkzap.orion.moe/developers/inbound-webhook
openapi: https://linkzap.orion.moe/openapi.json
---

# Webhook de entrada

Uma URL por número: qualquer sistema que saiba fazer um POST — formulário de site, CRM, Zapier, Make, n8n — vira contato, mensagem e fluxo aqui dentro, sem você escrever código.

## Onde pegar a URL e a chave

No painel, **Canais**: cada número tem a própria URL de webhook e o próprio botão **Copiar chave de API**. Os dois andam juntos — a chave do canal é a que abre aquela URL.

URL — O formato da URL:

```
https://linkzap.orion.moe/api/webhooks/channel/SEU_CHANNEL_ID
```

Abrir essa URL no navegador (um `GET`) devolve o contrato em JSON — útil para conferir que copiou a URL certa.

## O que mandar

### `POST /api/webhooks/channel/{id}`
Cria ou atualiza o contato pelo telefone e, se pedido, manda a mensagem ou inicia o fluxo — tudo num POST.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `phone` | texto | obrigatório | DDI + DDD + número. |
| `name` | texto | — | Nome do contato. |
| `email` | texto | — | E-mail válido. |
| `message` | texto | — | Um texto para enviar ao contato pelo canal. Use **ou** isto **ou** `flowId`, nunca os dois. |
| `flowId` | texto | — | Em vez de texto: inicia este fluxo na conversa do contato. |
| `tags` | lista | — | Até 20 etiquetas; as que não existem são criadas. Podem disparar um fluxo por si sós. |
| `fields` | objeto | — | Campos próprios seus (origem, número do pedido, o que fizer sentido). |
| `optIn` | booleano | — | Registra o consentimento — marque só se a pessoa de fato autorizou. |

Pedido:

```bash
curl -X POST https://linkzap.orion.moe/api/webhooks/channel/SEU_CHANNEL_ID \
  -H "x-api-key: lz_CHAVE_DO_CANAL" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5592999990000",
    "name": "Maria Souza",
    "message": "Oi, Maria! Recebemos o seu pedido de contato. Em que posso ajudar?",
    "tags": ["lead-site"],
    "fields": { "origem": "formulario-contato" },
    "optIn": true
  }'
```

Resposta:

```json
{
  "data": {
    "contactId": "ctt_3c81...",
    "created": true,
    "channelId": "chn_9f2a...",
    "conversationId": "cnv_5ad2...",
    "messageId": "msg_7bd0..."
  }
}
```

## O que volta

- `201` — criou o contato, ou enviou a mensagem, ou iniciou o fluxo.
- `200` — **só num caso**: o contato já existia e você não pediu mensagem nem fluxo.
- `403` — a chave é de outro canal.
- `409` — o número não está pronto para enviar. **O contato foi salvo mesmo assim**; só a mensagem não saiu.
- `503` — este servidor está sem a conexão de sistema; o webhook fica indisponível até alguém configurá-la.

Os campos de `data` dependem do que você pediu: sempre `contactId`, `created` e `channelId`; mais `conversationId` e `messageId` quando houve mensagem; mais `conversationId` e `flow: "started"` quando houve fluxo.

## Quando usar este, e quando usar a API

Este webhook é um atalho: faz num POST o que seriam duas ou três chamadas da API (criar contato, garantir conversa, enviar ou iniciar fluxo). Use-o quando quem chama é uma ferramenta sem código — um formulário, um automatizador, um gatilho do seu CRM.

Quando quem chama é o _seu_ backend, prefira a API: ela devolve mais informação, separa as responsabilidades e não obriga a mandar contato e mensagem no mesmo pacote.

> [!WARNING]
> **Não é o webhook que te avisa**
>
> Este é o que _você_ chama. Para receber aqui o que acontece lá — mensagem do contato, conversa resolvida —, o que você quer é a outra página: [Webhooks de saída](https://linkzap.orion.moe/developers/webhooks.md).