Recibir notificaciones sobre eventos dentro de una organización Omny Studio
Los webhooks permiten que sus servicios reciban solicitudes HTTP POST que le notifiquen eventos relevantes, como cuando se crea un clip o se actualiza un programa.
Crear y administrar suscripciones de webhook
Puede crear múltiples suscripciones a webhooks desde la página "Webhooks" de la "Configuración de la organización" o a nivel de red en Configuración de red - Webhooks como se ve en esta captura de pantalla:
Deberá ingresar la URL de su extremo receptor y elegir los eventos que desea recibir.
Una vez que haya configurado una suscripción y la haya habilitado, los eventos a los que se haya suscrito comenzarán a enviarse a ese extremo.
La página de suscripción al webhook también incluye detalles de los eventos enviados. De forma predeterminada, puede ver los 100 eventos más recientes, incluidos los cuerpos completos de solicitud y respuesta. También puede filtrar esta lista para ver errores recientes o tipos de eventos específicos.
Detalles técnicos de implementación
Cuerpo de la solicitud de Webhook
El cuerpo de la solicitud del webhook es un objeto JSON con las siguientes propiedades
Type(cadena) - el tipo de evento que causó que el webhook se disparara. Estos están estructurados como{entity}{change-type}por ejemploProgramCreated,ClipDeleted, etc.Timestamp(cadena) - el momento en que ocurrió el evento (exacto al segundo)ChangeId(Guid): un GUID que representa este cambio único. Este ID será común en varios suscriptores para el mismo evento.EventId(Guid): un GUID que representa este evento único para un suscriptor determinado.Current(objeto) - la representación de la entidad en el momento en que ocurrió el evento. El modelo de corriente variará según el tipo de evento, los eventos de clip enviarán un modelo de clip, los eventos de lista de reproducción una lista de reproducción, los eventos de programa un programa. Los modelos coinciden con lo que la API de administración usa para cada una de estas entidades.
Un ejemplo de una solicitud es
{
"Type": "ClipDeleted",
"Timestamp": "2019-10-09T10:25:56",
"Current": { ... }
}Tiempo de entrega del evento
Puede haber un pequeño retraso desde que se producen las acciones hasta que se envían los eventos de webhook. En promedio, el evento puede tardar entre 30 y 60 segundos en enviarse.
Este retraso variará según el número de suscripciones a webhooks activas, la acumulación de eventos que se enviarán y el tiempo de respuesta del servidor o servidores que reciben los webhooks.
Si bien generalmente haremos un mejor intento para entregar webhooks en secuencia, el cliente debe manejar la recepción de eventos fuera de orden. Específicamente, los reintentos pueden hacer que un evento antiguo se envíe después de los eventos más recientes. Puede consultar la Timestamp propiedad para un registro de cuándo ocurrió originalmente el evento.
Errores de entrega de eventos
Cualquier respuesta con un código de estado HTTP no exitoso (por ejemplo, no 2XX) se tratará como un error y se volverá a intentar la entrega del evento. Volveremos a intentar entregar el mensaje hasta 5 veces con un retroceso exponencial de hasta 60 minutos para entregar el evento.
Si un evento sigue fallando después del 5º intento, el evento webhook fallará permanentemente y no se volverá a intentar. Si se produce un error en diez mensajes consecutivos, la suscripción de webhook se deshabilitará y cualquier evento pendiente para esa suscripción se marcará como fallido permanentemente. Se enviará una notificación por correo electrónico al "contacto técnico de la organización" cuando se deshabilite la suscripción a webhook. La suscripción se puede volver a habilitar manualmente si desea seguir recibiendo eventos. Tenga en cuenta que los eventos que ocurrieron mientras se deshabilitó la suscripción no se enviarán, incluso después de volver a habilitar la suscripción.
Deduplicación de eventos
Aunque generalmente intentamos desduplicar eventos, es posible que enviemos un evento más de una vez.
Los receptores deben verificar que la solicitud es única a través de X-Omny-Event-Id Encabezado HTTP en la solicitud. Esto representa el ID de la solicitud que identifica de forma única este evento y permite la correlación con el intento de enviar la solicitud.
Si se pone en contacto con el servicio de asistencia técnica, incluya la X-Omny-Event-Id para identificar el evento en cuestión.
Seguridad
Para asegurarte de que los mensajes que recibes fueron enviados por Omny Studio, puedes configurar una clave secreta compartida para tus suscripciones de webhook que puedes verificar usando el X-Omny-Signature Encabezado HTTP de la solicitud. Recomendamos encarecidamente el uso de este proceso de verificación para evitar que agentes malintencionados envíen a los extremos del receptor del webhook.
Los módulos X-Omny-Signature El valor de la cabecera HTTP se genera mediante la función hash HMAC-SHA256
Clave: el valor secreto compartido
Valor: el cuerpo de la solicitud (codificación UTF-8, sin cabecera HTTP)
Verifique que el hash generado codificado en hexadecimal (sin agregar 0x inicial) coincida con el valor proporcionado en el X-Omny-Signature Encabezado HTTP en su solicitud recibida.
También te recomendamos encarecidamente que uses un extremo HTTPS para la suscripción de webhook. Los eventos enviados a una URL HTTPS validarán que el certificado TLS sea válido y esté firmado por una autoridad de confianza.