Webhooks
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, as mesmas tentativas, 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.
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:
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
Seção intitulada “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 oevent_typesaceitar. Só chave de organização e membro com acesso a todas as conexões criam ou enxergam. O receptor separa as conexões pelo campoconnectiondo envelope. O global casa uma vez por evento.
Dois filtros de exemplo:
{ "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.
{ "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
Seção intitulada “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. Nos exemplos abaixo, verify é a função daquela página (Python) e verifyWebhookSignature vem do SDK (Node).
A entrega é pelo menos uma vez: desduplique por Messajo-Event-Id.
RabbitMQ
Seção intitulada “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.
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);});import jsonimport 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
Seção intitulada “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).
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 })); }}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"]) # processe event["type"] / event["data"] sqs.delete_message(QueueUrl=queue_url, ReceiptHandle=msg["ReceiptHandle"])| 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.
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 },});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()) # processe event["type"] / event["data"]WebSocket
Seção intitulada “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
Seção intitulada “Conectar”- Peça um ticket com uma chave
read:POST /v1/destinations/{id}/ws-ticketsdevolve{ ticket, url, expires_at }. O ticket vale 60 segundos e uma conexão só. - Abra
url(wss://api.messajo.com/v1/ws?ticket=wst_…). - Sem ticket, também vale
Authorization: Bearer <chave read>com?destination_id=dst_…, para clientes que mandam cabeçalho no handshake.
Protocolo
Seção intitulada “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 sem2xx. Oacksó vale na sessão do mesmo destino. - Assinatura:
signatureé o mesmoMessajo-Signature, calculado sobre os bytes deeventexatamente 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_connectede entra nas tentativas normais.
| Código de fechamento | Motivo |
|---|---|
4401 |
ticket ou chave inválidos (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) |
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).
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"] # 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_..."))