Descripción general
- Alcances configurables para la cobertura de calendar y señales, de modo que solo recibas los datos que necesitas
- Entregas idempotentes con un encabezado único
X-BZ-Deliveryy un campoiden la carga útil para la deduplicación - Estrategia de reintentos sólida que escala desde reintentos exponenciales rápidos hasta intentos por hora a largo plazo
- Transformaciones de content opcionales para alinear las cargas útiles con las expectativas de los sistemas posteriores
Entrega de webhooks
Detalles de la solicitud HTTP
- Método:
POST - Content-Type:
application/json - User-Agent:
Benzinga-Dispatch/v1.0.0 {build-version} - Encabezado personalizado:
X-BZ-Delivery- Un UUID único para cada intento de entrega (útil para evitar duplicados)
Política de reintentos
- Fase exponencial: 15 reintentos durante los primeros 5 minutos
- Reintentos exponenciales adicionales: 11 reintentos más si es necesario
- Fase de intervalo fijo: 12 reintentos por hora × 24 horas/día × 7 días (para reintentos a largo plazo)
- Tiempo máximo de espera: 5 minutos entre reintentos en la fase exponencial
- Tiempo de espera de la solicitud: 30 segundos por solicitud
Requisitos de la respuesta
- Códigos de éxito (200-202, 204): Indican una entrega correcta. No se realizarán nuevos intentos.
- Códigos de error de cliente (401-403): Indican un error de autenticación/autorización. Los reintentos se detendrán inmediatamente para evitar más intentos fallidos.
- Otros códigos (4xx, 5xx): Activarán reintentos según la política de reintentos indicada arriba.
Estructura del payload del webhook
Campos del payload
Campos principales
id(string, UUID): Identificador único de esta entrega de webhook. Úsalo para evitar duplicados.api_version(string): Identificador de la versión de la API. Actualmente"webhook/v1".kind(string): Identificador de la ruta del tipo de datos. Consulta Tipos de datos compatibles para ver todos los valores posibles.
Objeto de datos
action(string): Tipo de acción del evento. Posibles valores:"Created": Se crearon nuevos datos (valor predeterminado para nuevas claves de webhook)"Updated": Se actualizaron datos existentes"Removed": Se eliminaron datos- Nota: Las claves de webhook heredadas pueden recibir valores en minúsculas:
"created","updated","removed"
id(string): Identificador único del registro de calendar o señaltimestamp(string, ISO 8601): Momento en que se generó el webhookcontent(object): Los datos de calendar o señal propiamente dichos. La estructura varía según el tipo de datos (consulta Tipos de datos compatibles)
Tipos de datos admitidos
Tipos de datos del calendar (v2.1)
| Tipo de dato | Kind Path | Descripción |
|---|---|---|
| Earnings | data/v2.1/calendar/earnings | Anuncios de resultados de empresas |
| Dividends | data/v2.1/calendar/dividends | Declaraciones y pagos de dividendos |
| Ratings | data/v2.1/calendar/ratings | Calificaciones de analistas y precios objetivo |
| IPOs | data/v2.1/calendar/ipos | Ofertas públicas iniciales |
| Guidance | data/v2.1/calendar/guidance | Actualizaciones de guidance de empresas |
| Conference | data/v2.1/calendar/conference | Conferencias telefónicas y presentaciones |
| Economics | data/v2.1/calendar/economics | Indicadores y comunicados económicos |
| Offerings | data/v2.1/calendar/offerings | Ofertas secundarias |
| Mergers & Acquisitions | data/v2.1/calendar/ma | Anuncios de M&A |
| Retail | data/v2.1/calendar/retail | Datos de ventas minoristas |
| Splits | data/v2.1/calendar/splits | Desdoblamientos de acciones |
| FDA | data/v2.1/calendar/fda | Aprobaciones y anuncios de la FDA |
Tipos de datos de señales (v1)
| Tipo de datos | Kind Path | Descripción |
|---|---|---|
| Actividad de opciones | data/v1/signal/option_activity | Actividad inusual de opciones |
| WIIMs | data/v1/wiims | Datos de Why Is It Moving (WIIMs) |
| Transacciones internas de la SEC | data/v1/sec/insider_transactions/filings | Declaraciones de operaciones internas ante la SEC |
| Operaciones gubernamentales | data/v1/gov/usa/congress | Datos de operaciones del Congreso de EE. UU. |
Tipos de datos adicionales (v1)
| Tipo de dato | Ruta Kind | Descripción |
|---|---|---|
| Bulls Say Bears Say | data/v1/bulls_bears_say | Análisis de sentimiento del mercado |
| Bulls Say Bears Say (Korean) | data/v1/bulls_bears_say/korean | Sentimiento del mercado coreano |
| Analyst Insights | data/v1/analyst/insights | Opiniones y comentarios de analistas |
| Consensus Ratings | data/v1/consensus-ratings | Calificaciones de consenso agregadas |
Ejemplos de estructuras de contenido
Ejemplo de resultados
Ejemplo de dividendos
Ejemplo de calificaciones
Ejemplo de actividad en opciones
Acciones de eventos
- Created: Se activa cuando se publican nuevos datos de calendario o de señales
- Updated: Se activa cuando se modifican datos existentes
- Removed: Se activa cuando se eliminan datos
- Nuevas claves de webhook: Reciben acciones con mayúscula inicial (
"Created","Updated","Removed") - Claves de webhook heredadas: Reciben acciones en minúsculas (
"created","updated","removed")
Filtrado de contenido
Opciones de filtrado
- Tipos de datos: Filtra por tipos específicos de calendario/señal (p. ej., solo ganancias, solo calificaciones)
- Filtros geográficos: Controla si recibes:
- Datos del mercado de EE. UU. (
AllowUSA) - Datos del mercado canadiense (
AllowCanada) - Datos del mercado indio (
AllowIndia) - para datos de WIIMs
- Datos del mercado de EE. UU. (
- Filtro de fecha: Excluye datos históricos anteriores a una fecha específica (
MaxHistoricalDate)
Filtrado por exchange
- Exchanges de EE. UU.: NYSE, NASDAQ, AMEX, ARCA, OTC, OTCBB, PINX, PINK, BATS, IEX
- Exchanges canadienses: TSX, TSXV, CSE, CNSX
Transformación de contenido
- Cambio de nombre de campos
- Conversión de formato de datos
- Filtrado/eliminación de campos
Prácticas recomendadas
1. Idempotencia
id (UUID) del payload para implementar la idempotencia. Almacene los ID de entregas ya procesadas para evitar procesarlas más de una vez.
2. Gestión de respuestas
- Devolver
200 OKo204 No Contentinmediatamente tras recibir el webhook - Procesar los datos de forma asíncrona si es necesario
- No ejecutar operaciones de larga duración antes de responder
3. Gestión de errores
- Devolver códigos de estado HTTP apropiados
- Para errores de autenticación (401-403), asegurarse de que el endpoint esté configurado correctamente
- Para fallos temporales, devolver códigos de estado 5xx para activar reintentos
4. Seguridad
- Usa HTTPS para tu endpoint de webhook
- Implementa autenticación y autorización (claves de API, tokens, etc.)
- Valida el encabezado
X-BZ-Deliverypara mayor seguridad
5. Supervisión
- Supervisa los tiempos de respuesta de tu endpoint
- Configura alertas para fallos reiterados
- Realiza un seguimiento del encabezado
X-BZ-Deliverypara identificar intentos de entrega
6. Gestión de tipos de datos
- Comprueba el campo
kindpara determinar el tipo de dato - Analiza el objeto
contentsegún la estructura de ese tipo de dato - Gestiona diferentes formatos de acción (mayúsculas vs. minúsculas) si se admiten claves heredadas
Ejemplo de controlador de webhook
Python (Flask)
Node.js (Express)
Go
Solución de problemas
Problemas comunes
-
No se reciben webhooks
- Verifica que la URL de tu webhook esté configurada correctamente
- Comprueba que tu endpoint sea accesible públicamente
- Asegúrate de que tu API key sea válida y esté activa
- Verifica que los filtros no estén excluyendo todos los tipos de datos
- Comprueba que tus filtros geográficos coincidan con los datos que esperas
-
Entregas duplicadas
- Implementa idempotencia usando el campo
id - Revisa los tiempos de respuesta de tu endpoint (las respuestas lentas pueden provocar reintentos)
- Implementa idempotencia usando el campo
-
Errores de autenticación (401-403)
- Verifica la configuración de autenticación de tu endpoint
- Comprueba las API keys y los tokens
- Nota: Los errores de autenticación detienen los reintentos inmediatamente
-
Errores de tiempo de espera (timeout)
- Asegúrate de que tu endpoint responda en menos de 30 segundos
- Procesa los datos de forma asíncrona si es necesario
- Devuelve una respuesta de éxito inmediatamente y procesa después
-
Formato de acción inesperado
- Comprueba si estás usando una webhook key antigua (acciones en minúsculas)
- Actualiza a una webhook key nueva para recibir acciones con mayúscula inicial
- Maneja ambos formatos si das soporte a múltiples clientes
-
Tipos de datos que faltan
- Verifica que la configuración de tu webhook incluya los tipos de datos deseados
- Revisa los filtros geográficos (configuraciones US/Canada/India)
- Asegúrate de que los filtros de fecha no estén excluyendo datos recientes
Soporte
- Consulta la Documentación de la API de Benzinga
- Ponte en contacto con tu representante de cuenta de Benzinga
- Revisa la configuración del webhook con tu equipo de integración
Historial de versiones
- v1.0.0: Lanzamiento inicial del servicio de webhooks de datos
- Versión actual: Mecanismos mejorados de filtrado, transformación y reintentos