Início rápido

Este guia vai do zero a um evento entregue, conferido e com o histórico de tentativas na tela. Tudo acontece no ambiente de desenvolvimento, que existe para você integrar sem sujar o histórico de produção.

Antes de começar

Você precisa de uma chave de API do ambiente de desenvolvimento, que começa com whk_test_, e de uma URL pública que aceite POST para receber o webhook. Crie a chave no painel, dentro do projeto, no ambiente de desenvolvimento.

Os exemplos leem a chave de uma variável de ambiente:

export NOTYFACIL_KEY=whk_test_xxxxxxxxxxxxxxxxxxxx

1. Cadastre o tipo de evento.

   Só tipos cadastrados podem ser publicados. É o que impede um erro de digitação de virar um evento que ninguém recebe.

   curl -X POST https://api.notyfacil.com.br/v1/event-types \
     -H "Authorization: Bearer $NOTYFACIL_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name":"pedido.pago"}'

2. Cadastre o Consumer.

   O Consumer é quem recebe, normalmente um cliente seu. O externalId é o id dele no seu sistema, e é por ele que você o referencia daqui para a frente.

   curl -X POST https://api.notyfacil.com.br/v1/consumers \
     -H "Authorization: Bearer $NOTYFACIL_KEY" \
     -H "Content-Type: application/json" \
     -d '{"externalId":"cliente-42","name":"Padaria do Zé"}'

3. Cadastre o endpoint e guarde o secret.

   curl -X POST https://api.notyfacil.com.br/v1/endpoints \
     -H "Authorization: Bearer $NOTYFACIL_KEY" \
     -H "Content-Type: application/json" \
     -d '{"consumer":"cliente-42","url":"https://padariadoze.com.br/webhooks","events":["pedido.pago"]}'

   { "id": "ep_01JB8Y1D6TQ4X8N2VK5HWZ3RFM", "url": "https://padariadoze.com.br/webhooks", "events": ["pedido.pago"], "secret": "whsec_…" }

   O secret aparece só nesta resposta. É com ele que o receptor confere a assinatura; se perder, o caminho é rotacionar.

4. Teste o endpoint antes de publicar.

   curl -X POST https://api.notyfacil.com.br/v1/endpoints/ep_01JB8Y1D6TQ4X8N2VK5HWZ3RFM/test \
     -H "Authorization: Bearer $NOTYFACIL_KEY"

   A chamada espera a entrega de teste e devolve o que aconteceu. success: true quer dizer que a sua URL respondeu 2xx; é a hora de conferir se a verificação de assinatura do seu lado aceitou.

5. Publique o evento.

   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-1234-pago',
     },
     body: JSON.stringify({
       consumer: 'cliente-42',
       type: 'pedido.pago',
       data: { pedidoId: 1234, valorCentavos: 4990 },
     }),
   })
   
   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-1234-pago',
       ],
       CURLOPT_POSTFIELDS => json_encode([
           'consumer' => 'cliente-42',
           'type' => 'pedido.pago',
           'data' => ['pedidoId' => 1234, 'valorCentavos' => 4990],
       ]),
   ]);
   
   $evento = json_decode(curl_exec($ch), true);

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

   202 quer dizer aceito e gravado, não entregue. deliveries é quantas Entregas foram criadas; zero quer dizer que nenhum endpoint está inscrito no tipo.

6. Confira a entrega e as tentativas.

   curl https://api.notyfacil.com.br/v1/events/evt_01JB8XZQ4T9M2NKPWV3RYCF7HD/deliveries \
     -H "Authorization: Bearer $NOTYFACIL_KEY"
   
   curl https://api.notyfacil.com.br/v1/deliveries/dlv_01JB8Y3K7QF2V9D5WZ0XH4M1RC/attempts \
     -H "Authorization: Bearer $NOTYFACIL_KEY"

   Cada tentativa traz o status HTTP que a sua URL devolveu, a duração e o começo da resposta. O mesmo histórico aparece no painel.

E agora

• Leia as garantias de entrega antes de ir para produção: elas mudam o código de quem recebe.
• Mande o link de verificando a assinatura para quem vai implementar o receptor.
• Em produção, a chave é whk_live_ e a URL do endpoint precisa ser https. Veja ambientes e chaves.