Usa esta guía para enviar los errores de integración de Fin a tus propios sistemas en tiempo real. Cuando agregas un webhook, Fin envía una solicitud POST firmada a tu URL cada vez que aparece un nuevo error en los registros de errores, para que puedas dirigirlo a tu sistema de alertas, tickets o monitoreo.
Nota: Los webhooks de registros de errores están disponibles para Fin en espacios de trabajo de plataformas conectadas a Salesforce, HubSpot, Freshdesk o Zendesk.
Antes de comenzar
Necesitas el permiso Gestionar aplicaciones e integraciones para agregar, probar o eliminar el webhook. Sin él, puedes seleccionar Solicitar permiso en el panel de Webhook.
Tu endpoint debe ser accesible públicamente a través de HTTPS. Al guardar, Fin envía una solicitud HEAD para verificar que sea accesible.
Tu endpoint debe devolver un código de estado 2xx en menos de 7 segundos.
Cómo agregar un webhook
Ve a Configuración > Registros de errores (bajo Integraciones).
Haz clic en Webhook en la parte superior derecha de la página.
En URL del webhook, ingresa tu endpoint, por ejemplo
your-server.example.com/error-logs. El prefijohttps://se añade automáticamente.Selecciona Guardar. Verás «Webhook guardado» cuando la URL sea validada.
(Opcional) Copia el Secreto de firma que aparece debajo de la URL. Lo usarás para verificar que las solicitudes provienen de Fin.
Selecciona Probar para enviar un evento de prueba a tu endpoint. Verás «Prueba enviada» si tu endpoint responde correctamente.
Nota: La prueba envía un evento
ping, no un registro de error. Asegúrate de que tu endpoint acepte ambos temas (ver ejemplos abajo).
Qué envía Fin a tu webhook
Fin envía una solicitud por cada nuevo error que aparece en los registros de errores. Si el mismo error se repite para la misma conversación en una hora, puede que solo se registre y envíe una vez.
Cada solicitud es un POST con un cuerpo JSON y estos encabezados:
Content-Type: application/json
X-Hub-Signature: la firma de la solicitud (ver Cómo verificar la firma).
Intercom-Webhook-Subscription-ID: el ID de tu suscripción al webhook.
Ejemplo de carga útil de registro de error
Los detalles del error están en data.item. El tema siempre es 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 del registro de error
id: el ID de la entrada del registro de error.
app_id: el ID de tu espacio de trabajo Fin.
created_at: cuándo ocurrió el error, como una marca de tiempo Unix en segundos.
environment: el entorno del helpdesk conectado, como tu organización Salesforce o subdominio Zendesk. Puede ser nulo.
error_code: el código de error devuelto por tu helpdesk, por ejemplo INVALID_FIELD.
error_message: el mensaje de error devuelto por tu helpdesk.
request_status, request_method y request_path: el estado HTTP, método y ruta de la solicitud que falló.
object_type: el objeto del helpdesk involucrado, por ejemplo Case o Knowledge__kav.
api_type: la API del helpdesk que Fin estaba llamando, por ejemplo salesforce_rest_api, hubspot_rest_api, freshdesk_rest_api o zendesk_rest_api.
product_feature: la función de Fin afectada, por ejemplo salesforce_cases, fin_messenger, knowledge_import o historical_conversations_import.
integration_type: la integración de Fin de donde provino el error, por ejemplo salesforce_cases o zendesk_tickets.
conversation_id: la conversación relacionada de Fin, si existe. Puede ser nulo.
Nota: Estos campos coinciden con lo que ves en el panel Detalles del error en los registros de errores. Para entender y corregir un código de error específico, consulta Fin para Salesforce: Soluciona errores comunes de integración.
Importante: error_message y request_path provienen directamente de tu helpdesk y pueden incluir datos de registros, como valores de campos o IDs. Guarda las cargas útiles de forma segura.
Ejemplo de carga útil de prueba
{
"type": "notification_event",
"topic": "ping",
"data": {
"type": "notification_event_data",
"item": {
"type": "ping",
"message": "This is a ping notification test message."
}
}
}
Cómo verificar la firma
Cada solicitud incluye un encabezado X-Hub-Signature. Es un HMAC-SHA1 del cuerpo bruto de la solicitud, firmado con tu secreto de firma, en el formato sha1=<digest hexadecimal>.
Para verificar una solicitud:
Calcula un HMAC-SHA1 del cuerpo bruto de la solicitud, antes de analizar el JSON, usando tu secreto de firma como clave.
Prefija el digest hexadecimal con sha1=.
Compáralo con el encabezado X-Hub-Signature usando una comparación en tiempo constante. Rechaza la solicitud si no coinciden.
Por ejemplo, en Ruby:
expected = "sha1=" + OpenSSL::HMAC.hexdigest("SHA1", signing_secret, raw_body)
valid = Rack::Utils.secure_compare(expected, request.headers["X-Hub-Signature"])Importante: Mantén tu secreto de firma privado. Verlo o copiarlo queda registrado en el registro de actividad de compañeros de tu espacio de trabajo.
Entrega y reintentos
Una entrega se considera exitosa cuando tu endpoint devuelve un código de estado 2xx. Fin no sigue redirecciones, así que usa la URL final de tu endpoint.
Si tu endpoint se agota el tiempo o devuelve un error, Fin reintentará la entrega automáticamente.
Si tu endpoint devuelve 410 Gone, Fin deja de enviarle solicitudes inmediatamente.
Fin puede enviar el mismo evento más de una vez. Usa el id de nivel superior del evento para ignorar duplicados.
Fin puede entregar eventos fuera de orden. Usa created_at para ordenarlos.
Fin envía una solicitud por error, por lo que una caída en tu helpdesk puede enviar muchas solicitudes en poco tiempo. Responde rápido y procesa eventos en segundo plano.
Mensajes de estado del webhook
Si las entregas fallan, el panel de Webhook muestra uno de estos mensajes:
Pausado: «Tu endpoint está devolviendo errores, por lo que las entregas están pausadas. Reintentaremos automáticamente.» No se requiere acción si el problema es temporal.
Suspendido: «Tu endpoint siguió devolviendo errores, por lo que las entregas están suspendidas.» Corrige tu endpoint y luego selecciona Guardar nuevamente para reconectar.
Desactivado: «Tu endpoint devolvió 410 Gone, por lo que las entregas se detuvieron.» Selecciona Guardar nuevamente para reconectar.
Detenido por Fin: «Fin ha detenido las entregas a este webhook.» Contacta al soporte para reanudarlas.
Cómo eliminar un webhook
Ve a Configuración > Registros de errores y selecciona Webhook.
Selecciona el icono de la papelera junto a la URL.
Selecciona Eliminar webhook para confirmar.
Fin deja de enviar nuevos registros de errores a esa URL. Los que ya estén en camino pueden llegar. Puedes agregar un webhook en cualquier momento. Si lo haces, se crea un nuevo secreto de firma, así que actualízalo en tu endpoint.
Preguntas frecuentes
¿Puedo enviar registros de errores a más de una URL?
¿Puedo enviar registros de errores a más de una URL?
Todavía no. Cada espacio de trabajo puede tener un webhook de registros de errores.
¿Puedo elegir qué errores se envían?
¿Puedo elegir qué errores se envían?
No. Fin envía cada nuevo error que aparece en los registros de errores. Puedes filtrar por campos como product_feature, api_type o error_code en tu propio sistema.
¿Fin envía errores pasados cuando agrego un webhook?
¿Fin envía errores pasados cuando agrego un webhook?
No. Solo se envían los errores registrados después de guardar el webhook.
¿Por qué la prueba no envió un registro de error?
¿Por qué la prueba no envió un registro de error?
El botón Probar envía un evento ping para verificar que tu endpoint sea accesible. Los registros de error reales usan el tema error_log.created.
¿Puedo cambiar o regenerar el secreto de firma?
¿Puedo cambiar o regenerar el secreto de firma?
El secreto permanece igual mientras el webhook esté configurado. Para obtener un nuevo secreto, elimina el webhook y agrégalo de nuevo.

