# Tipos de destino

> Webhook, RabbitMQ, SQS, Kafka e WebSocket: configuração, exemplo de consumidor em Node e Python e como verificar a assinatura em cada um.

Todo destino recebe o mesmo envelope, com a mesma assinatura, os mesmos [filtros](/webhooks/events/#filtros), as mesmas [tentativas](/webhooks/events/#tentativas-e-falhas), a mesma lista de falhas e a mesma pausa automática. Muda só o transporte.

| Tipo | Quando usar | Ligado por padrão |
|---|---|---|
| `webhook` | Você tem uma URL HTTPS | sim |
| `rabbitmq` | Seus serviços já consomem de um exchange AMQP | não|
| `sqs` | Você está na AWS e quer uma fila gerenciada | não|
| `kafka` | Você tem um cluster Kafka e quer ordem por conexão | não|
| `websocket` | Seu processo não tem URL pública (script, desktop, ambiente local) | não|

Tipo desligado não aparece no painel e criar ou editar um destino dele devolve `422` [`destination_type_disabled`](/errors#destination_type_disabled).

## Criar

No painel, **Destinos de eventos → Novo destino** e escolha o tipo. Pela API, `POST /v1/destinations` com `type` e um bloco com o nome do tipo:

```bash
curl https://api.messajo.com/v1/destinations \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Fila de eventos",
    "type": "rabbitmq",
    "rabbitmq": {
      "url": "amqps://messajo:senha@mq.suaempresa.com:5671/producao",
      "exchange": "messajo",
      "routing_key": "messajo.{type}"
    },
    "event_types": ["message.*"],
    "format": "normalized"
  }'
```

A resposta traz o segredo de assinatura (`whsec_…`) uma vez só, como no webhook. Senhas e chaves do bloco nunca voltam: a resposta mostra só os 4 últimos caracteres. `POST /v1/destinations/{id}/test` funciona para todos os tipos.

Em `routing_key` (RabbitMQ), `message_group_id` (SQS) e `key` (Kafka) valem os marcadores `{type}`, `{family}`, `{connection}`, `{channel}` e `{org}`; o resto é texto fixo.

## Global ou por conexão

Todo destino é de uma conexão ou **global** (da organização). O campo `connection_id` decide: um id é o destino daquela conexão; `null` é o global.

- **Por conexão**: recebe só os eventos daquela conexão. Criado no painel da conexão, em **Destinos**.
- **Global**: é o webhook da organização. Recebe os eventos sem conexão (`org.standing_changed`), o ciclo de vida das conexões (`connection.*`) e qualquer evento de qualquer conexão que o `event_types` aceitar. Só chave de organização e membro com acesso a todas as conexões criam ou enxergam. O receptor separa as conexões pelo campo `connection` do envelope. O global casa uma vez por evento.

Dois filtros de exemplo:

```json
{ "connection_id": null, "event_types": ["connection.*", "org.*"] }
```

Global só com os eventos da organização: ciclo de vida das conexões e situação da conta.

```json
{ "connection_id": null, "event_types": ["*"] }
```

Global com todos os eventos de todas as conexões.

`connection_ids` (lista) é um apelido **obsoleto** de `connection_id`: aceita `null` ou um único id. Mais de um id devolve `400` `validation_failed`; crie um destino por conexão. A resposta traz os dois campos.

## Assinatura em todos os tipos

O corpo é o mesmo envelope JSON do webhook e os cabeçalhos `Messajo-*` vão como **cabeçalhos da mensagem** (headers no RabbitMQ e no Kafka, `MessageAttributes` no SQS). Verifique `Messajo-Signature` sobre o corpo cru, igual ao webhook: veja [Verificar a assinatura](/webhooks/verify-signature/). Nos exemplos abaixo, `verify` é a função daquela página (Python) e `verifyWebhookSignature` vem do [SDK](/sdk/typescript/) (Node).

A entrega é **pelo menos uma vez**: desduplique por `Messajo-Event-Id`.

## RabbitMQ

| Campo | Padrão | O que é |
|---|---|---|
| `url` | — | `amqps://usuário:senha@host:5671/vhost` |
| `exchange` | — | exchange que já existe no seu servidor |
| `routing_key` | `messajo.{type}` | chave de roteamento |
| `persistent` | `true` | mensagem gravada em disco no broker |

O Messajo publica num canal com confirmação e espera o `ack` do broker por até 10 segundos. `nack` ou tempo esgotado contam como falha e entram nas tentativas. Cada mensagem leva `messageId` = id do evento e `type` = tipo do evento.

```ts title="Node (amqplib)"
import amqp from "amqplib";
import { verifyWebhookSignature } from "@messajo/sdk";

const connection = await amqp.connect(process.env.AMQP_URL!);
const channel = await connection.createChannel();
const { queue } = await channel.assertQueue("messajo-eventos", { durable: true });
await channel.bindQueue(queue, "messajo", "messajo.message.*");

await channel.consume(queue, async (msg) => {
  if (!msg) return;
  const body = msg.content.toString("utf8");
  const header = String(msg.properties.headers?.["Messajo-Signature"] ?? "");
  const check = await verifyWebhookSignature({ header, body, secret: process.env.MESSAJO_SECRET! });
  if (!check.ok) return channel.nack(msg, false, false);
  const event = JSON.parse(body);
  // processe event.type / event.data
  channel.ack(msg);
});
```

```python title="Python (pika)"
import json
import os

import pika

from verify import verify  # a função de "Verificar a assinatura"

connection = pika.BlockingConnection(pika.URLParameters(os.environ["AMQP_URL"]))
channel = connection.channel()
channel.queue_declare("messajo-eventos", durable=True)
channel.queue_bind("messajo-eventos", "messajo", "messajo.message.*")


def handle(ch, method, properties, body: bytes) -> None:
    header = (properties.headers or {}).get("Messajo-Signature", "")
    if not verify(header, body, os.environ["MESSAJO_SECRET"]):
        ch.basic_nack(method.delivery_tag, requeue=False)
        return
    event = json.loads(body)
    # processe event["type"] / event["data"]
    ch.basic_ack(method.delivery_tag)


channel.basic_consume("messajo-eventos", handle)
channel.start_consuming()
```

## Amazon SQS

| Campo | Padrão | O que é |
|---|---|---|
| `queue_url` | — | `https://sqs.<região>.amazonaws.com/<conta>/<fila>` |
| `region` | — | região da fila |
| `access_key_id` · `secret_access_key` · `session_token` | — | credencial IAM só com `sqs:SendMessage` nessa fila |
| `message_group_id` | `{connection}` | só em fila `.fifo`: ordem por conexão |

Em fila `.fifo`, o `MessageDeduplicationId` é o id da entrega. Os cabeçalhos `Messajo-*` vão em `MessageAttributes`. O SQS aceita até 1 MiB por mensagem: evento maior falha sem nova tentativa com `payload_too_large` (aparece na lista de falhas).

```ts title="Node (@aws-sdk/client-sqs)"
import { DeleteMessageCommand, ReceiveMessageCommand, SQSClient } from "@aws-sdk/client-sqs";
import { verifyWebhookSignature } from "@messajo/sdk";

const sqs = new SQSClient({});
const QueueUrl = process.env.QUEUE_URL!;

for (;;) {
  const { Messages = [] } = await sqs.send(
    new ReceiveMessageCommand({ QueueUrl, MessageAttributeNames: ["All"], WaitTimeSeconds: 20 })
  );
  for (const msg of Messages) {
    const header = msg.MessageAttributes?.["Messajo-Signature"]?.StringValue ?? null;
    const check = await verifyWebhookSignature({ header, body: msg.Body!, secret: process.env.MESSAJO_SECRET! });
    if (check.ok) {
      const event = JSON.parse(msg.Body!);
      // processe event.type / event.data
    }
    await sqs.send(new DeleteMessageCommand({ QueueUrl, ReceiptHandle: msg.ReceiptHandle }));
  }
}
```

```python title="Python (boto3)"
import json
import os

import boto3

from verify import verify

sqs = boto3.client("sqs")
queue_url = os.environ["QUEUE_URL"]

while True:
    response = sqs.receive_message(
        QueueUrl=queue_url, MessageAttributeNames=["All"], WaitTimeSeconds=20
    )
    for msg in response.get("Messages", []):
        attributes = msg.get("MessageAttributes", {})
        header = attributes.get("Messajo-Signature", {}).get("StringValue", "")
        if verify(header, msg["Body"].encode(), os.environ["MESSAJO_SECRET"]):
            event = json.loads(msg["Body"])
            # processe event["type"] / event["data"]
        sqs.delete_message(QueueUrl=queue_url, ReceiptHandle=msg["ReceiptHandle"])
```

## Kafka

| Campo | Padrão | O que é |
|---|---|---|
| `brokers` | — | até 10, `host:porta` |
| `topic` | — | tópico que já existe |
| `ssl` | `true` | TLS |
| `sasl` | `null` | `{ mechanism: "plain" \| "scram-sha-256" \| "scram-sha-512", username, password }` |
| `key` | `{connection}` | chave da mensagem: mesma chave, mesma partição, mesma ordem |
| `client_id` | `messajo` | id do cliente no cluster |

O produtor é idempotente e espera todas as réplicas (`acks: -1`), com 10 segundos de limite. Os cabeçalhos `Messajo-*` vão nos headers da mensagem.

```ts title="Node (kafkajs)"
import { Kafka } from "kafkajs";
import { verifyWebhookSignature } from "@messajo/sdk";

const kafka = new Kafka({ brokers: process.env.KAFKA_BROKERS!.split(","), ssl: true });
const consumer = kafka.consumer({ groupId: "messajo-eventos" });
await consumer.connect();
await consumer.subscribe({ topic: "messajo" });

await consumer.run({
  eachMessage: async ({ message }) => {
    const body = message.value?.toString("utf8") ?? "";
    const header = message.headers?.["Messajo-Signature"]?.toString() ?? null;
    const check = await verifyWebhookSignature({ header, body, secret: process.env.MESSAJO_SECRET! });
    if (!check.ok) return;
    const event = JSON.parse(body);
    // processe event.type / event.data
  },
});
```

```python title="Python (confluent-kafka)"
import json
import os

from confluent_kafka import Consumer

from verify import verify

consumer = Consumer({
    "bootstrap.servers": os.environ["KAFKA_BROKERS"],
    "security.protocol": "SSL",
    "group.id": "messajo-eventos",
})
consumer.subscribe(["messajo"])

while True:
    msg = consumer.poll(1.0)
    if msg is None or msg.error():
        continue
    headers = dict(msg.headers() or [])
    header = headers.get("Messajo-Signature", b"").decode()
    if verify(header, msg.value(), os.environ["MESSAJO_SECRET"]):
        event = json.loads(msg.value())
        # processe event["type"] / event["data"]
```

## WebSocket

O seu processo abre a conexão e o Messajo empurra os eventos por ela. Não precisa de URL pública nem de porta aberta. O destino `websocket` não tem configuração: crie com `"type": "websocket"`.

### Conectar

1. Peça um ticket com uma chave `read`: `POST /v1/destinations/{id}/ws-tickets` devolve `{ ticket, url, expires_at }`. O ticket vale 60 segundos e uma conexão só.
2. Abra `url` (`wss://api.messajo.com/v1/ws?ticket=wst_…`).
3. Sem ticket, também vale `Authorization: Bearer <chave read>` com `?destination_id=dst_…`, para clientes que mandam cabeçalho no handshake.

### Protocolo

Todos os quadros são JSON em texto.

| Direção | Quadro | O que fazer |
|---|---|---|
| servidor → você | `{"type":"ready","destination_id","session_id","heartbeat_s":30}` | conectado |
| servidor → você | `{"type":"event","delivery_id","attempt","signature","event":{...}}` | processe e mande o `ack` |
| servidor → você | `{"type":"ping","t"}` | responda `{"type":"pong","t"}` com o mesmo `t` |
| você → servidor | `{"type":"ack","delivery_id"}` | confirma a entrega |

- **Ack:** sem `ack`, a entrega fica pendente e volta na próxima tentativa, como um webhook sem `2xx`. O `ack` só vale na sessão do mesmo destino.
- **Assinatura:** `signature` é o mesmo `Messajo-Signature`, calculado sobre os bytes de `event` exatamente como aparecem no quadro. A sessão já é autenticada pelo ticket; verificar é opcional.
- **Sessões:** até 5 por destino. Todas recebem os eventos: desduplique por `event.id`. A ordem não é garantida.
- Sem cliente conectado, a entrega falha com `no_client_connected` e entra nas tentativas normais.

| Código de fechamento | Motivo |
|---|---|
| `4401` | ticket ou chave inválidos ([`ws_ticket_invalid`](/errors#ws_ticket_invalid)) |
| `4403` | o destino não é `websocket` ou não está ativo |
| `4408` | sem `pong` por 75 segundos |
| `4410` | o destino foi apagado |
| `4429` | já há 5 sessões ([`ws_session_limit`](/errors#ws_session_limit)) |

```ts title="Node (SDK)"
import { Messajo, connectEvents } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
const socket = connectEvents({
  client: messajo,
  destinationId: "dst_...",
  onEvent: async (event) => {
    // o ack sai quando isto resolve; se lançar, o Messajo entrega de novo
    console.log(event.type);
  },
});
await socket.ready;
```

O `connectEvents` pede o ticket, responde o `ping`, manda o `ack` e reconecta com espera crescente (1 s até 30 s). No Node 20, passe a opção `WebSocket` (do pacote `ws`).

```python title="Python (websockets)"
import asyncio
import json
import os

import requests
import websockets

API = "https://api.messajo.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['MESSAJO_API_KEY']}"}


async def main(destination_id: str) -> None:
    while True:
        ticket = requests.post(
            f"{API}/destinations/{destination_id}/ws-tickets", headers=HEADERS, timeout=10
        ).json()
        async with websockets.connect(ticket["url"]) as ws:
            async for raw in ws:
                frame = json.loads(raw)
                if frame["type"] == "ping":
                    await ws.send(json.dumps({"type": "pong", "t": frame["t"]}))
                elif frame["type"] == "event":
                    event = frame["event"]
                    # processe event["type"] / event["data"]
                    await ws.send(json.dumps({"type": "ack", "delivery_id": frame["delivery_id"]}))
        await asyncio.sleep(1)


asyncio.run(main("dst_..."))
```
