Webhooks

Configuração de Webhooks

O Umbrella envia notificações por Webhook aos seus sistemas externos quando ocorrem eventos de garantia. Use Webhooks para integrar com seu CRM, central de atendimento, ferramentas de análise ou serviços de backend.

---

Tipos de evento

Eventos de apólice

Evento	Descrição
policy.created	Apólice de garantia criada (pedido concluído com garantia)
policy.activated	Apólice ativada (pagamento confirmado)
policy.expired	A apólice chegou à data de término
policy.cancelled	Apólice cancelada (reembolso ou cancelamento do pedido)
policy.updated	Apólice atualizada (mudança de status ou de metadados)

Eventos de sinistro

Evento	Descrição
claim.created	Novo sinistro registrado
claim.updated	Status do sinistro alterado
claim.approved	Sinistro aprovado
claim.denied	Sinistro negado
claim.resolved	Sinistro resolvido (substituto enviado ou reembolso emitido)

Eventos de pedido

Evento	Descrição
order.warranty_attached	Garantia vinculada a um item de linha do pedido
order.warranty_removed	Garantia removida de um pedido
order.post_purchase_completed	Venda adicional de garantia pós-compra concluída

Eventos de cliente

Evento	Descrição
customer.policy_assigned	Apólice atribuída a um cliente
customer.claim_filed	O cliente registrou um sinistro

---

Formato do payload

Todos os payloads seguem esta estrutura:

{
  "id": "wh_evt_abc123def456",
  "event": "policy.created",
  "timestamp": "2026-03-17T14:30:00.000Z",
  "version": "1.0",
  "data": { ... },
  "metadata": {
    "orgId": "org_abc",
    "integrationPlatform": "shopify",
    "shopDomain": "my-store.myshopify.com"
  }
}

• id — ID exclusivo do evento (use para eliminar duplicatas)
• event — tipo de evento
• data — payload específico do evento, com os detalhes do recurso
• metadata — contexto da organização e da integração

---

Verificação de assinatura

Todos os Webhooks incluem um cabeçalho X-Umbrella-Signature (HMAC-SHA256 do corpo da requisição). Sempre verifique a assinatura antes de processar. Consulte a Referência de webhooks para ver exemplos de código de verificação.

---

Política de novas tentativas

Entregas com falha (resposta diferente de 2xx ou tempo esgotado) são repetidas com backoff exponencial:

Tentativa	Intervalo
1ª nova tentativa	30 segundos
2ª nova tentativa	2 minutos
3ª nova tentativa	10 minutos
4ª nova tentativa	1 hora
5ª nova tentativa	6 horas
Última tentativa	24 horas

Seu endpoint precisa responder com 200, 201 ou 202 em até 30 segundos. Responda imediatamente e processe de forma assíncrona para evitar tempo esgotado.

---

Configurar um endpoint

1. Acesse Painel → Configurações → Webhooks
2. Clique em Adicionar endpoint
3. Informe a URL HTTPS do seu endpoint e selecione os eventos
4. Copie e guarde com segurança o segredo de assinatura (exibido apenas uma vez)
5. Teste usando Enviar evento de teste na página de detalhes do endpoint

---

Logs de Webhooks

A página de logs mostra o histórico de entregas de cada endpoint: tipo de evento, status (sucesso/falha/repetido), código de resposta, tempo de resposta, data e hora e número de tentativas.

---

Relacionados

• Sincronização de produtos da Shopify — Sincronização por Webhooks da Shopify
• Integração com a Shopify — Conexão geral com a Shopify
• Configuração de widgets — Configurações de exibição do widget