Publicando eventos

Publicar é uma chamada. Ela grava o evento, cria uma Entrega para cada endpoint do Consumer que ouve aquele tipo, e responde antes de entregar.

cURL

curl -X POST https://api.notyfacil.com.br/v1/events \
  -H "Authorization: Bearer $NOTYFACIL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234-pago" \
  -d '{
        "consumer": "cliente-42",
        "type": "pedido.pago",
        "data": { "pedidoId": 1234, "valorCentavos": 4990 }
      }'

Node.js

const resposta = await fetch('https://api.notyfacil.com.br/v1/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOTYFACIL_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `pedido-${pedido.id}-pago`,
  },
  body: JSON.stringify({
    consumer: pedido.clienteId,
    type: 'pedido.pago',
    data: { pedidoId: pedido.id, valorCentavos: pedido.valorCentavos },
  }),
})

if (!resposta.ok) throw new Error(`Notyfacil respondeu ${resposta.status}`)
const evento = await resposta.json()

PHP

$ch = curl_init('https://api.notyfacil.com.br/v1/events');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('NOTYFACIL_KEY'),
        'Content-Type: application/json',
        "Idempotency-Key: pedido-{$pedido->id}-pago",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'consumer' => $pedido->clienteId,
        'type' => 'pedido.pago',
        'data' => ['pedidoId' => $pedido->id, 'valorCentavos' => $pedido->valorCentavos],
    ]),
]);

$evento = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

{ "id": "evt_01JB8XZQ4T9M2NKPWV3RYCF7HD", "status": "queued", "deliveries": 2 }

O corpo

Campo
consumer	O externalId do Consumer. Obrigatório.
type	O nome de um tipo de evento cadastrado. Obrigatório.
data	O que você quiser mandar, em JSON, até 256 KB. Vai para o receptor sem alteração.

A resposta

202 quer dizer aceito e gravado, não entregue. A partir daqui o evento não se perde: a intenção de entregar foi gravada na mesma transação.

deliveries é quantas Entregas foram criadas. Zero quer dizer que nenhum endpoint do Consumer ouve esse tipo: o evento fica registrado e não vai a lugar nenhum. Não é erro, e é o caso comum de um cliente que ainda não configurou nada.

O que o receptor recebe

O data chega dentro de um envelope, assinado:

POST /webhooks HTTP/1.1
Content-Type: application/json
User-Agent: Notyfacil/1.0
Webhook-Id: evt_01JB8XZQ4T9M2NKPWV3RYCF7HD
Webhook-Timestamp: 1757337600
Webhook-Signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{"id":"evt_01JB8XZQ4T9M2NKPWV3RYCF7HD","type":"pedido.pago","createdAt":"2026-09-08T13:20:00.000Z","data":{"pedidoId":1234,"valorCentavos":4990}}

O id do envelope é o mesmo do Webhook-Id, e createdAt é o instante da publicação. É por ele que o receptor ordena, nunca pela chegada. O resto é com quem recebe.

Publique com Idempotency-Key

Dica

Mande sempre uma Idempotency-Key derivada do fato, como pedido-1234-pago. Se a chamada der timeout, repita com a mesma chave: a repetição devolve o evento original, com 200 e Idempotency-Replayed: true, em vez de publicar de novo.

Os detalhes estão em idempotência.

Quando dá errado

Status	O que fazer
402	A quota mensal do plano Free acabou. Nada é publicado até o upgrade ou a virada do mês.
413	data passa de 256 KB. Mande a referência e deixe o receptor buscar o resto.
422	Consumer ou tipo não cadastrado, ou campo obrigatório ausente. O title diz qual.
429	Limite de requisições. Espere o Retry-After e repita com a mesma Idempotency-Key.
5xx ou timeout	Repita com a mesma Idempotency-Key.

Onde publicar no seu código

Publique depois que o fato estiver gravado no seu banco. Publicar antes do commit anuncia um pedido pago que pode não existir, se a sua transação falhar.

Se o seu sistema não tolera perder o aviso entre o commit e a chamada, grave a intenção numa tabela sua na mesma transação e publique a partir dela, com a Idempotency-Key protegendo as repetições.

Referência: publicar um evento · listar eventos