Ir al contenido

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:

Ventana de terminal
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.

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:

{ "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.

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.

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.

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 (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()
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).

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 (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"])
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.

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 (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"]

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".

  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.

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)
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)
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 (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_..."))