Solicitação

O que o webhook me envia?

O webhook envia um evento via HTTP POST requisição com Content-Type: application/json com os seguintes parâmetros:

• Um X-Caf-Signature cabeçalho usado para verificar se a requisição veio da Certta

Assinatura

• O corpo da requisição é um JSON que segue o padrão CloudEvents

Eventos

Estrutura da requisição

Cada requisição de webhook inclui:

Cabeçalhos

Cabeçalho	Descrição
Content-Type	Sempre application/json
User-Agent	Identifica-se como Caf-Webhook/Connect
X-Caf-Signature	Contém a assinatura HMAC SHA-256 do corpo da requisição

Corpo da requisição

O corpo da requisição segue o formato CloudEvents, embora os cabeçalhos HTTP específicos do CloudEvents não estejam incluídos:

{
  "specversion": "1.0",
  "type": "COMMUNICATIONCREATEDEVENT",
  "source": "COMMUNICATION",
  "id": "01JZNK5ZQBNF623MB5KE64GNQB",
  "time": "2025-07-08T18:01:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "channel": "sms",
    "externalId": "external-id",
    "notificationId": "01JZNK51YCZXT55TKF8M366QHJ",
    "system": "onboarding",
    "occurredOn": "2025-07-08T18:00:46.797Z"
  }
}

Exemplos

Curl

Exemplo de comando curl assumindo SECRET: "dummysecret":

curl --location 'http://localhost:8080/webhook' \
--header 'X-Caf-Signature: 6f9ed23a7b505a3b6907c5f6eb2ad1b056fbf35a643d365a9a072ed7aabca153' \
--header 'Content-Type: application/json' \
--data '{
  "specversion": "1.0",
  "type": "COMMUNICATIONCREATEDEVENT",
  "source": "COMMUNICATION",
  "id": "01JZNK5ZQBNF623MB5KE64GNQB",
  "time": "2025-07-08T18:01:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "channel": "sms",
    "externalId": "external-id",
    "notificationId": "01JZNK51YCZXT55TKF8M366QHJ",
    "system": "onboarding",
    "occurredOn": "2025-07-08T18:00:46.797Z"
  }
}'

É importante validar a assinatura do payload assim que ele chegar (como um array de bytes), sem qualquer análise das informações. Isso garante a integridade da verificação.

O que devo responder ao webhook?

Nosso webhook considera respostas com um 2xx código (de preferência 202 ACCEPTED) em até 2 segundos como indicação de que a integração recebeu o evento com sucesso e, portanto, nenhuma outra chamada será feita para esse evento. O corpo da resposta é ignorado pelo sistema, exceto para fins de auditoria interna em caso de falhas de entrega.

Casos de erro

A requisição de webhook tem o objetivo de integrar o evento com sucesso e nada além disso. Com esse objetivo em mente, as respostas de erro devem ser usadas apenas para indicar falha na integração do evento (por evento integrado, entende-se que o evento foi recebido com sucesso pelo servidor de webhook).

O mecanismo de entrega do webhook aceita e reconhece erros dentro da série de erros HTTP 5xx, que podem indicar erros no recebimento ou processamento da requisição pelo servidor. As retentativas de entrega ocorrerão apenas para essa classe de erros.

As respostas de erro podem seguir o payload especificado abaixo para detalhar e deixar claro o motivo do erro em nossa auditoria interna. Quaisquer outros campos e/ou formatos serão ignorados.

{
  "error": "mensagem de erro"
}

Se todas as tentativas de entrega falharem, o webhook descarta o evento, que não será mais entregue via webhook!

O número máximo de tentativas, o intervalo entre cada tentativa de entrega e o tempo limite ficam a critério da Certta. Atualmente, consideramos requisições que demoram mais de 2 segundos para responder como timeout e tentamos reenviar os eventos por até 15 minutos.

Tratamento de requisições de webhook

Idempotência

As requisições de webhook podem ser entregues mais de uma vez em casos raros. Para lidar com isso, implemente idempotência por meio de:

1. Usando o id campo no payload do evento para detectar duplicatas
2. Armazenando IDs de eventos processados para evitar processar o mesmo evento duas vezes
3. Tornando sua lógica de tratamento de eventos idempotente (segura para executar várias vezes)

Exemplo de manipulador de webhook

Aqui está um exemplo simples de manipulador de webhook em Node.js Express:

const express = require('express');
const bodyParser = require('body-parser');
const crypto = require('crypto');

const app = express();
app.use(bodyParser.json());

app.post('/webhook', (req, res) => {
  const sigHeader = req.headers['x-caf-signature'];
  const payload = req.body;
  
  // Verifique a assinatura
  if (!verifySignature(payload, sigHeader, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Assinatura inválida');
  }
  
  // Processe o CloudEvent com base em seu tipo
  const eventType = payload.type;
  const eventSource = payload.source;
  const eventId = payload.id;
  
  console.log(`Processando CloudEvent: ${eventId} da origem ${eventSource} do tipo ${eventType}`);
  
  switch (eventType) {
    case 'COMMUNICATIONCREATEDEVENT':
      handleCommunicationCreated(payload.data);
      break;
    case 'TRANSACTIONPROCESSSTARTEDEVENT':
      handleTransactionProcessStarted(payload.data);
      break;
    case 'TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT':
      handleTransactionDocumentsCopyRequested(payload.data);
      break;
    case 'TRANSACTIONSTATUSUPDATEDEVENT':
      handleTransactionUpdated(payload.data);
      break;
    case 'PROFILEUPDATEDEVENT':
      handleProfileUpdated(payload.data);
      break;
    // Trate outros tipos de evento...
    default:
      console.log(`Tipo de evento não tratado: ${eventType}`);
  }
  
  // Responda com sucesso
  res.status(200).send('Evento recebido');
});

// Inicie o servidor
app.listen(3000, () => {
  console.log('Servidor de webhook ouvindo na porta 3000');
});

Solução de problemas

Problemas comuns

401 Unauthorized

• Seu endpoint retornou um código 401.
• Verifique se você está validando as assinaturas corretamente.

Tempo limite

• Seu endpoint demorou demais para responder.
• Otimize seu código para responder em menos de 2 segundos.

Conexão recusada

• A Certta não conseguiu se conectar ao seu endpoint.
• Verifique se seu servidor está em execução e acessível.

Rejeição de assinatura

• Falha na validação da assinatura do webhook.
• Verifique se você está usando o segredo correto e validando os bytes brutos do corpo.

Logs e depuração

Você pode usar os logs de webhook no Trust, a plataforma que gerencia configurações, para visualizar o status de entrega dos eventos recentes e quaisquer mensagens de erro. Os logs mantêm um histórico de:

• Tentativas de entrega bem-sucedidas e com falha
• Códigos de resposta HTTP recebidos
• Carimbos de data e hora das entregas
• Erros específicos encontrados durante as entregas