Vista General

Los webhooks te permiten suscribirte a eventos de Sheriff y recibir las respuestas en tu propio servidor de forma asíncrona. En vez de tener que consultar repetidamente la API esperando que un dato esté listo, configurás una URL destino y Sheriff te entrega la información cuando corresponde.

Configuración desde el Dashboard

La configuración de los webhooks (URL destino, OAuth 2.0, headers personalizados) se realiza desde el dashboard web de Sheriff en Integraciones → Webhooks, no vía API.

¿Cómo funciona?

1. Configura uno o varios webhooks desde el dashboard web. Para cada tipo de evento puedes tener hasta 3 configuraciones activas, cada una con una sola URL destino y su propia configuración de seguridad (headers, OAuth, secretKey).
2. Dispara el envío vía API llamando al endpoint correspondiente al tipo de webhook (ver tabla de abajo).
3. Sheriff crea un evento (triggerId) que agrupa la llamada. Si tienes varias configuraciones activas, dispara una entrega por cada una en paralelo, todas vinculadas al mismo triggerId.
4. Recibe los datos en cada URL configurada.
5. Audita el evento desde el dashboard, en la sección Integraciones → Webhooks. Cada llamada aparece como una sola fila en el historial; al abrir el detalle puedes ver el estado individual de cada entrega.

Tipos de Webhook Disponibles

Tipo	Endpoint para dispararlo	Documentación
Descarga Resumen de Perfil	POST /v1/webhook/perfiles/resumen	Ver detalle

Estructura del Payload — Campos Comunes

Todo webhook que entrega Sheriff incluye al menos estos dos campos en el body:

Campo	Tipo	Descripción
triggerId	string	Identificador único del evento. Mismo valor que en el header X-Sheriff-Trigger-Id.
data	object	Datos correspondientes al evento. Su estructura depende del tipo de webhook.

Cada tipo de webhook puede agregar campos adicionales (estados de carga, errores específicos, metadata del evento, etc.). Consulta la página de cada tipo para ver el payload completo que recibirás.

triggerId compartido

Si tienes varias configuraciones activas, todas tus URLs recibirán el mismo triggerId para la misma llamada. Eso te permite identificar en tu lado que las recepciones corresponden al mismo evento, aunque lleguen por distintos endpoints.

Versión del Payload

Cada configuración de webhook declara con qué versión del resumen se entrega su data. La regla es simple: la versión del payload del webhook es la versión del resumen que lleva adentro — data tiene exactamente la misma estructura que la respuesta del endpoint REST de esa versión (/v1 o /v2).

La versión se elige por configuración desde el dashboard, en Integraciones → Webhooks:

Versión	Estado	data equivale a
v1	Estable (por defecto)	GET /v1/perfiles/:taxId/resumen
v2	Beta	GET /v2/perfiles/:taxId/resumen

Qué cambia entre versiones y qué no:

• Solo cambia data. El sobre del webhook — triggerId, taxId, profileLoadStatus, failedSubhelpers, la firma X-Sheriff-Signature y los headers — es el mismo en ambas versiones.
• En v2 el estado de carga viaja además dentro de data (estado, subhelpers_fallidos y statusCode por sección), con más detalle que los campos del envelope. Los campos del envelope se mantienen por compatibilidad y se deprecarán con fecha anunciada cuando v2 sea estable.
• Las diferencias de contrato entre v1 y v2 son las mismas del REST: consulta la guía de migración v1 → v2.
• Cada configuración resuelve su versión de forma independiente: puedes tener una configuración en v1 apuntando a producción y otra en v2 apuntando a tu ambiente de pruebas, y probar v2 en paralelo sin tocar producción.
• El cambio aplica a las entregas posteriores al guardado: una carga de perfil en curso al momento del cambio puede entregarse ya con la versión nueva.
• Volver a v1 es cambiar el selector de vuelta — sin coordinación con Sheriff.

v2 está en beta

El contrato de data en v2 todavía puede cambiar antes de declararse estable. Los cambios se anuncian por contacto directo y changelog, igual que en una versión estable — beta acorta el plazo de aviso, no lo elimina. Si validas el body contra un JSON-schema estricto, actualízalo antes de cambiar de versión: la firma HMAC no se rompe (se calcula sobre el body real), pero tu schema sí puede romperse.

Perfiles no reprocesados

Un perfil cargado antes del modelo nuevo entrega en v2 las mismas degradaciones transitorias que el REST v2: comex.pendiente_de_calculo: true con las banderas en null, y finanzas.situacion: null. El dato se completa con la siguiente actualización del perfil. Ver la guía de migración para la semántica exacta.

Headers que Recibirás

Header	Descripción
Content-Type	Siempre application/json.
X-Sheriff-Signature	Firma HMAC-SHA256 del body (ver sección de seguridad).
X-Sheriff-Trigger-Id	Identificador único del evento, igual al que está dentro del payload.
Authorization	Presente solo si configuraste OAuth 2.0. Formato: Bearer <token>.
Headers personalizados	Cualquier header adicional que hayas configurado en el dashboard.

Reintentos Automáticos

Cada destino se procesa de forma independiente en una cola SQS con reintentos automáticos:

• 3 intentos totales por destino antes de marcar la entrega como fallida.
• Si tu servidor responde con un error 5xx, timeout o un error de red, Sheriff volverá a intentar la entrega.
• Los errores 4xx también generan reintentos, excepto 401/403 que se clasifican como error de autenticación.
• Si todas las entregas (de todas las configuraciones activas) fallan, el evento queda en estado FAILED. Si al menos una entrega es exitosa, el evento queda en estado SUCCEEDED.

Respuesta exitosa esperada

Para considerar una entrega como exitosa, tu servidor debe responder con un código HTTP 2xx dentro de 30 segundos. Cualquier otra respuesta o un timeout se considera fallo y gatilla un reintento.

Estados del Evento

Estos estados reflejan la salud de la entrega HTTP y son visibles en el dashboard.

Estado	Descripción
LOADING_PROFILE	El evento está esperando que algo previo termine (por ejemplo, la carga de un perfil).
PENDING	Encolado, aún no procesado.
PROCESSING	Al menos una entrega está siendo enviada en este momento.
SUCCEEDED	Al menos una entrega llegó con éxito (2xx). Si tienes varias configuraciones, basta con una.
FAILED	Todas las entregas fallaron tras agotar sus reintentos. Revisa el detalle en el dashboard.

Auditoría detallada

Dentro del dashboard, al abrir el detalle de un evento puedes ver el estado individual de cada entrega: a qué URL se envió, cuántos intentos tomó, qué código HTTP devolvió, y el mensaje de error si aplica. Estos detalles son solo para auditoría — el cliente externo recibe únicamente el triggerId.

Próximos Pasos

• Integración — configuración paso a paso en el dashboard y verificación de firma.
• Descarga Resumen de Perfil — detalle del único tipo de webhook disponible actualmente.