Webhooks
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, los mismos reintentos, 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.
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:
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:[email protected]: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
Sección titulada «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 acepteevent_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 campoconnectiondel sobre. El global coincide una vez por evento.
Dos filtros de ejemplo:
{ "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.
{ "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
Sección titulada «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. En los ejemplos de abajo, verify es la función de esa página (Python) y verifyWebhookSignature viene del SDK (Node).
La entrega es al menos una vez: deduplica por Messajo-Event-Id.
RabbitMQ
Sección titulada «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.
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);});import jsonimport 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
Sección titulada «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).
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 })); }}import jsonimport 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"])| 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.
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 },});import jsonimport 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
Sección titulada «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
Sección titulada «Conectar»- Pide un ticket con una clave
read:POST /v1/destinations/{id}/ws-ticketsdevuelve{ ticket, url, expires_at }. El ticket vale 60 segundos y una sola conexión. - Abre
url(wss://api.messajo.com/v1/ws?ticket=wst_…). - Sin ticket, también vale
Authorization: Bearer <clave read>con?destination_id=dst_…, para clientes que mandan cabeceras en el handshake.
Protocolo
Sección titulada «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 sin2xx. Elacksolo vale en una sesión del mismo destino. - Firma:
signaturees el mismoMessajo-Signature, calculado sobre los bytes deeventtal 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_connectedy entra en los reintentos normales.
| Código de cierre | Motivo |
|---|---|
4401 |
ticket o clave inválidos (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) |
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).
import asyncioimport jsonimport os
import requestsimport 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_..."))