Pular para o conteúdo

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:

Janela do terminal
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:[email protected]: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.

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:

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

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.

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.

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

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

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

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

  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.

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