Use este guia para enviar os erros de integração do Fin para seus próprios sistemas conforme acontecem. Quando você adiciona um webhook, o Fin envia uma requisição POST assinada para sua URL toda vez que um novo erro aparece nos logs de erro, para que você possa direcioná-lo para seu sistema de alertas, tickets ou monitoramento.
Nota: Webhooks de logs de erro estão disponíveis para Fin em workspaces de plataformas conectadas ao Salesforce, HubSpot, Freshdesk ou Zendesk.
Antes de começar
Você precisa da permissão Gerenciar apps e integrações para adicionar, testar ou remover o webhook. Sem ela, você pode selecionar Solicitar permissão no painel do Webhook.
Seu endpoint deve ser acessível publicamente via HTTPS. Ao salvar, o Fin envia uma requisição HEAD para verificar se está acessível.
Seu endpoint deve retornar um código de status 2xx em até 7 segundos.
Como adicionar um webhook
Vá para Configurações > Logs de erro (em Integrações).
Clique em Webhook no canto superior direito da página.
Em URL do Webhook, insira seu endpoint, por exemplo
your-server.example.com/error-logs. O prefixohttps://é adicionado automaticamente.Selecione Salvar. Você verá “Webhook salvo” quando a URL for validada.
(Opcional) Copie o Segredo de assinatura mostrado abaixo da URL. Você usará para verificar que as requisições vêm do Fin.
Selecione Testar para enviar um evento de teste para seu endpoint. Você verá “Teste enviado” se seu endpoint responder com sucesso.
Nota: O teste envia um evento
ping, não um log de erro. Certifique-se de que seu endpoint aceite ambos os tópicos (veja os exemplos abaixo).
O que o Fin envia para seu webhook
O Fin envia uma requisição para cada novo erro que aparece nos logs de erro. Se o mesmo erro se repetir para a mesma conversa dentro de uma hora, ele pode ser registrado e enviado apenas uma vez.
Cada requisição é um POST com um corpo JSON e estes cabeçalhos:
Content-Type: application/json
X-Hub-Signature: a assinatura da requisição (veja Como verificar a assinatura).
Intercom-Webhook-Subscription-ID: o ID da sua assinatura do webhook.
Exemplo de payload de log de erro
Os detalhes do erro estão em data.item. O tópico é sempre error_log.created.
{
"type": "notification_event",
"app_id": "abc123de",
"topic": "error_log.created",
"id": "notif_1a2b3c4d",
"created_at": 1762430400,
"data": {
"type": "notification_event_data",
"item": {
"type": "error_log",
"id": "123",
"app_id": "abc123de",
"created_at": 1762430400,
"environment": {
"type": "environment",
"id": "456",
"name": "acme.my.salesforce.com",
"is_production": true
},
"error_code": "INVALID_FIELD",
"error_message": "No such column 'InvalidField' on entity 'Case'",
"request_status": 400,
"request_method": "POST",
"request_path": "/services/data/v58.0/sobjects/Case",
"object_type": "Case",
"api_type": "salesforce_rest_api",
"product_feature": "salesforce_cases",
"integration_type": "salesforce_cases",
"conversation_id": "789"
}
}
}
Campos do log de erro
id: o ID da entrada do log de erro.
app_id: o ID do seu workspace Fin.
created_at: quando o erro aconteceu, como timestamp Unix em segundos.
environment: o ambiente do helpdesk conectado, como sua organização Salesforce ou subdomínio Zendesk. Pode ser nulo.
error_code: o código de erro retornado pelo seu helpdesk, por exemplo INVALID_FIELD.
error_message: a mensagem de erro retornada pelo seu helpdesk.
request_status, request_method e request_path: o status HTTP, método e caminho da requisição que falhou.
object_type: o objeto do helpdesk envolvido, por exemplo Case ou Knowledge__kav.
api_type: a API do helpdesk que o Fin estava chamando, por exemplo salesforce_rest_api, hubspot_rest_api, freshdesk_rest_api ou zendesk_rest_api.
product_feature: o recurso do Fin afetado, por exemplo salesforce_cases, fin_messenger, knowledge_import ou historical_conversations_import.
integration_type: a integração do Fin de onde veio o erro, por exemplo salesforce_cases ou zendesk_tickets.
conversation_id: a conversa Fin relacionada, se houver. Pode ser nulo.
Nota: Esses campos correspondem ao que você vê no painel Detalhes do erro nos logs de erro. Para entender e corrigir um código de erro específico, veja Fin for Salesforce: Corrigir erros comuns de integração.
Importante: error_message e request_path vêm diretamente do seu helpdesk e podem incluir dados de registros, como valores de campos ou IDs. Armazene os payloads com segurança.
Exemplo de payload de teste
{
"type": "notification_event",
"topic": "ping",
"data": {
"type": "notification_event_data",
"item": {
"type": "ping",
"message": "This is a ping notification test message."
}
}
}
Como verificar a assinatura
Cada requisição inclui um cabeçalho X-Hub-Signature. É um HMAC-SHA1 do corpo bruto da requisição, assinado com seu segredo de assinatura, no formato sha1=<digest hexadecimal>.
Para verificar uma requisição:
Calcule um HMAC-SHA1 do corpo bruto da requisição, antes de analisar o JSON, usando seu segredo de assinatura como chave.
Prefixe o digest hexadecimal com sha1=.
Compare com o cabeçalho X-Hub-Signature usando uma comparação em tempo constante. Rejeite a requisição se não coincidirem.
Por exemplo, em Ruby:
expected = "sha1=" + OpenSSL::HMAC.hexdigest("SHA1", signing_secret, raw_body)
valid = Rack::Utils.secure_compare(expected, request.headers["X-Hub-Signature"])Importante: Mantenha seu segredo de assinatura privado. Visualizá-lo ou copiá-lo é registrado no log de atividade dos colegas do seu workspace.
Entrega e tentativas
Uma entrega é considerada bem-sucedida quando seu endpoint retorna um código de status 2xx. O Fin não segue redirecionamentos, então use a URL final do seu endpoint.
Se seu endpoint expirar ou retornar um erro, o Fin tenta a entrega novamente automaticamente.
Se seu endpoint retornar 410 Gone, o Fin para de enviar para ele imediatamente.
O Fin pode enviar o mesmo evento mais de uma vez. Use o id do nível superior do evento para ignorar duplicatas.
O Fin pode entregar eventos fora de ordem. Use created_at para ordená-los.
O Fin envia uma requisição por erro, então uma falha no seu helpdesk pode enviar muitas requisições em pouco tempo. Responda rapidamente e processe os eventos em segundo plano.
Mensagens de status do webhook
Se as entregas estiverem falhando, o painel do Webhook mostra uma destas mensagens:
Pausado: “Seu endpoint está retornando erros, então as entregas estão pausadas. Tentaremos novamente automaticamente.” Nenhuma ação é necessária se o problema for temporário.
Suspendido: “Seu endpoint continuou retornando erros, então as entregas estão suspensas.” Corrija seu endpoint e selecione Salvar novamente para reconectar.
Desativado: “Seu endpoint retornou 410 Gone, então as entregas foram interrompidas.” Selecione Salvar novamente para reconectar.
Parado pelo Fin: “O Fin parou as entregas para este webhook.” Contate o suporte para retomá-las.
Como remover um webhook
Vá para Configurações > Logs de erro e selecione Webhook.
Selecione o ícone de lixeira ao lado da URL.
Selecione Remover webhook para confirmar.
O Fin para de enviar novos logs de erro para essa URL. Quaisquer que já estejam a caminho ainda podem chegar. Você pode adicionar um webhook novamente a qualquer momento. Se fizer isso, um novo segredo de assinatura será criado, então atualize-o em seu endpoint.
Perguntas frequentes
Posso enviar logs de erro para mais de uma URL?
Posso enviar logs de erro para mais de uma URL?
Ainda não. Cada workspace pode ter um webhook de logs de erro.
Posso escolher quais erros são enviados?
Posso escolher quais erros são enviados?
Não. O Fin envia todos os novos erros que aparecem nos logs de erro. Você pode filtrar por campos como product_feature, api_type ou error_code no seu próprio sistema.
O Fin envia erros antigos quando adiciono um webhook?
O Fin envia erros antigos quando adiciono um webhook?
Não. Apenas erros registrados após salvar o webhook são enviados.
Por que o teste não enviou um log de erro?
Por que o teste não enviou um log de erro?
O botão Testar envia um evento ping para verificar se seu endpoint está acessível. Logs reais de erro usam o tópico error_log.created.
Posso alterar ou regenerar o segredo de assinatura?
Posso alterar ou regenerar o segredo de assinatura?
O segredo permanece o mesmo enquanto o webhook estiver configurado. Para obter um novo segredo, remova o webhook e adicione-o novamente.

