# Tipos de destino

> Webhook, RabbitMQ, SQS, Kafka y WebSocket: configuración, ejemplo de consumidor en Node y Python y cómo verificar la firma en cada uno.

Todo destino recibe el mismo sobre, con la misma firma, los mismos [filtros](/es/webhooks/events/#filtros), los mismos [reintentos](/es/webhooks/events/#reintentos-y-fallos), la misma lista de fallos y la misma pausa automática. Solo cambia el transporte.

| Tipo | Cuándo usarlo | Activo por defecto |
|---|---|---|
| `webhook` | Tienes una URL HTTPS | sí |
| `rabbitmq` | Tus servicios ya consumen de un exchange AMQP | no|
| `sqs` | Estás en AWS y quieres una cola gestionada | no|
| `kafka` | Tienes un clúster Kafka y quieres orden por conexión | no|
| `websocket` | Tu proceso no tiene URL pública (script, escritorio, entorno local) | no|

Un tipo desactivado no aparece en el panel, y crear o editar un destino de ese tipo devuelve `422` [`destination_type_disabled`](/es/errors#destination_type_disabled).

## Crear

En el panel, **Destinos de eventos → Nuevo destino** y elige el tipo. Por la API, `POST /v1/destinations` con `type` y un bloque con el nombre del tipo:

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

La respuesta trae el secreto de firma (`whsec_…`) una sola vez, como en el webhook. Las contraseñas y claves del bloque nunca vuelven: la respuesta muestra solo los 4 últimos caracteres. `POST /v1/destinations/{id}/test` funciona para todos los tipos.

En `routing_key` (RabbitMQ), `message_group_id` (SQS) y `key` (Kafka) valen los marcadores `{type}`, `{family}`, `{connection}`, `{channel}` y `{org}`; el resto es texto fijo.

## Global o por conexión

Todo destino es de una conexión o es **global** (de la organización). El campo `connection_id` lo decide: un id es el destino de esa conexión; `null` es el global.

- **Por conexión**: recibe solo los eventos de esa conexión. Se crea en el panel de la conexión, en **Destinos**.
- **Global**: es el webhook de la organización. Recibe los eventos sin conexión (`org.standing_changed`), el ciclo de vida de las conexiones (`connection.*`) y cualquier evento de cualquier conexión que acepte `event_types`. Solo clave de organización y miembro con acceso a todas las conexiones lo crean o lo ven. El receptor separa las conexiones por el campo `connection` del sobre. El global coincide una vez por evento.

Dos filtros de ejemplo:

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

Global solo con los eventos de la organización: ciclo de vida de las conexiones y estado de la cuenta.

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

Global con todos los eventos de todas las conexiones.

`connection_ids` (lista) es un alias **obsoleto** de `connection_id`: acepta `null` o un solo id. Más de un id devuelve `422` `validation_failed`; crea un destino por conexión. La respuesta trae los dos campos.

## Firma en todos los tipos

El cuerpo es el mismo sobre JSON del webhook y las cabeceras `Messajo-*` van como **cabeceras del mensaje** (headers en RabbitMQ y Kafka, `MessageAttributes` en SQS). Verifica `Messajo-Signature` sobre el cuerpo crudo, igual que en el webhook: consulta [Verificar la firma](/es/webhooks/verify-signature/). En los ejemplos de abajo, `verify` es la función de esa página (Python) y `verifyWebhookSignature` viene del [SDK](/es/sdk/typescript/) (Node).

La entrega es **al menos una vez**: deduplica por `Messajo-Event-Id`.

## RabbitMQ

| Campo | Por defecto | Qué es |
|---|---|---|
| `url` | — | `amqps://usuario:clave@host:5671/vhost` |
| `exchange` | — | exchange que ya existe en tu servidor |
| `routing_key` | `messajo.{type}` | clave de enrutamiento |
| `persistent` | `true` | mensaje grabado en disco en el broker |

Messajo publica en un canal con confirmación y espera el `ack` del broker hasta 10 segundos. Un `nack` o el tiempo agotado cuentan como fallo y entran en los reintentos. Cada mensaje lleva `messageId` = id del evento y `type` = tipo del 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);
  // procesa event.type / event.data
  channel.ack(msg);
});
```

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

import pika

from verify import verify  # la función de "Verificar la firma"

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)
    # procesa event["type"] / event["data"]
    ch.basic_ack(method.delivery_tag)


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

## Amazon SQS

| Campo | Por defecto | Qué es |
|---|---|---|
| `queue_url` | — | `https://sqs.<región>.amazonaws.com/<cuenta>/<cola>` |
| `region` | — | región de la cola |
| `access_key_id` · `secret_access_key` · `session_token` | — | credencial IAM solo con `sqs:SendMessage` en esa cola |
| `message_group_id` | `{connection}` | solo en cola `.fifo`: orden por conexión |

En una cola `.fifo`, el `MessageDeduplicationId` es el id de la entrega. Las cabeceras `Messajo-*` van en `MessageAttributes`. SQS acepta hasta 1 MiB por mensaje: un evento mayor falla sin reintentos con `payload_too_large` (aparece en la lista de fallos).

```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!);
      // procesa 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"])
            # procesa event["type"] / event["data"]
        sqs.delete_message(QueueUrl=queue_url, ReceiptHandle=msg["ReceiptHandle"])
```

## Kafka

| Campo | Por defecto | Qué es |
|---|---|---|
| `brokers` | — | hasta 10, `host:puerto` |
| `topic` | — | tópico que ya existe |
| `ssl` | `true` | TLS |
| `sasl` | `null` | `{ mechanism: "plain" \| "scram-sha-256" \| "scram-sha-512", username, password }` |
| `key` | `{connection}` | clave del mensaje: misma clave, misma partición, mismo orden |
| `client_id` | `messajo` | id del cliente en el clúster |

El productor es idempotente y espera a todas las réplicas (`acks: -1`), con 10 segundos de límite. Las cabeceras `Messajo-*` van en los headers del mensaje.

```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);
    // procesa 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())
        # procesa event["type"] / event["data"]
```

## WebSocket

Tu proceso abre la conexión y Messajo empuja los eventos por ella. No necesitas URL pública ni puerto abierto. El destino `websocket` no tiene configuración: créalo con `"type": "websocket"`.

### Conectar

1. Pide un ticket con una clave `read`: `POST /v1/destinations/{id}/ws-tickets` devuelve `{ ticket, url, expires_at }`. El ticket vale 60 segundos y una sola conexión.
2. Abre `url` (`wss://api.messajo.com/v1/ws?ticket=wst_…`).
3. Sin ticket, también vale `Authorization: Bearer <clave read>` con `?destination_id=dst_…`, para clientes que mandan cabeceras en el handshake.

### Protocolo

Todos los cuadros son JSON en texto.

| Dirección | Cuadro | Qué hacer |
|---|---|---|
| servidor → tú | `{"type":"ready","destination_id","session_id","heartbeat_s":30}` | conectado |
| servidor → tú | `{"type":"event","delivery_id","attempt","signature","event":{...}}` | procésalo y manda el `ack` |
| servidor → tú | `{"type":"ping","t"}` | responde `{"type":"pong","t"}` con el mismo `t` |
| tú → servidor | `{"type":"ack","delivery_id"}` | confirma la entrega |

- **Ack:** sin `ack`, la entrega queda pendiente y vuelve en el siguiente intento, como un webhook sin `2xx`. El `ack` solo vale en una sesión del mismo destino.
- **Firma:** `signature` es el mismo `Messajo-Signature`, calculado sobre los bytes de `event` tal como aparecen en el cuadro. La sesión ya está autenticada por el ticket; verificar es opcional.
- **Sesiones:** hasta 5 por destino. Todas reciben los eventos: deduplica por `event.id`. El orden no está garantizado.
- Sin cliente conectado, la entrega falla con `no_client_connected` y entra en los reintentos normales.

| Código de cierre | Motivo |
|---|---|
| `4401` | ticket o clave inválidos ([`ws_ticket_invalid`](/es/errors#ws_ticket_invalid)) |
| `4403` | el destino no es `websocket` o no está activo |
| `4408` | sin `pong` durante 75 segundos |
| `4410` | el destino fue borrado |
| `4429` | ya hay 5 sesiones ([`ws_session_limit`](/es/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) => {
    // el ack sale cuando esto se resuelve; si lanza, Messajo entrega de nuevo
    console.log(event.type);
  },
});
await socket.ready;
```

`connectEvents` pide el ticket, responde el `ping`, manda el `ack` y reconecta con espera creciente (de 1 s a 30 s). En Node 20, pasa la opción `WebSocket` (del paquete `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"]
                    # procesa event["type"] / event["data"]
                    await ws.send(json.dumps({"type": "ack", "delivery_id": frame["delivery_id"]}))
        await asyncio.sleep(1)


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