Referência de webhooks

Os webhooks enviam requisições HTTP POST para o seu endpoint quando ocorrem eventos no Umbrella, para que você não precise consultar a API repetidamente em busca de mudanças.

Configuração

1. Acesse Painel > Configurações > Integrações > Webhooks
2. Clique em Adicionar endpoint de webhook
3. Informe a URL HTTPS do seu endpoint
4. Selecione os eventos que deseja receber
5. Salve e guarde o segredo de assinatura (exibido apenas uma vez)

Seu endpoint deve aceitar requisições POST, retornar um status 2xx em até 30 segundos e aceitar application/json.

Tipos de evento

Eventos de apólice

Eventos de sinistro

Eventos de registro

Eventos de garantia

Estrutura do payload

Todo webhook segue este envelope:

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "claim.submitted",
  "timestamp": "2025-03-15T14:30:00.000Z",
  "apiVersion": "1.3.9",
  "orgId": "org_xyz789",
  "data": { ... }
}

• id — ID único do evento (use para eliminar duplicatas)
• type — tipo de evento
• timestamp — quando o evento ocorreu
• data — payload específico do evento, com os detalhes do recurso em questão (apólice, sinistro, registro etc.)

Verificação de assinatura

Toda requisição inclui um cabeçalho X-Umbrella-Signature com um hash HMAC-SHA256 do corpo da requisição. Verifique-o antes de processar os eventos.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Política de novas tentativas

Entregas com falha (status diferente de 2xx, tempo esgotado, erro de conexão) são repetidas com backoff exponencial:

Após 7 tentativas com falha, a entrega é marcada como falha. Uma resposta 410 Gone desativa o endpoint permanentemente.

Testes

1. Acesse Painel > Configurações > Integrações > Webhooks
2. Clique no seu endpoint e depois em Enviar evento de teste
3. Selecione um tipo de evento e confira o resultado da entrega

A página de detalhes do webhook também mostra um log das entregas recentes, com códigos de status e tempos.

Relacionados

• Autenticação — segurança e credenciais da API
• API de sinistros — endpoints de gerenciamento de sinistros
• API de apólices — endpoints de gerenciamento de apólices