Los webhooks envían automáticamente una solicitud HTTP POST a tu propio endpoint cuando se producen determinados eventos en Grabyo. Esto permite iniciar flujos de trabajo posteriores en cuanto se crea el contenido, sin necesidad de consultar constantemente la API para detectar nuevos clips, GIF o imágenes.
Cada webhook mantiene un historial de entregas que te permite ver qué se envió, comprobar si la entrega se realizó correctamente y volver a enviarla durante las pruebas o la resolución de problemas.
📕 Nota: Los webhooks están disponibles para todos los clientes que tengan acceso a la API. Consulta Acceso a la API para saber cómo habilitarlo.
¿Por qué utilizar webhooks?
Ventaja | Detalles |
Ya no es necesario consultar la API constantemente | Grabyo notifica automáticamente a tu sistema cuando se crea contenido, por lo que no es necesario consultar constantemente la API para detectar nuevos clips y otros recursos relacionados. |
Activadores casi en tiempo real | Los flujos de trabajo se inician en cuanto se produce el evento. |
Visibilidad del estado de las entregas | Cada intento de entrega queda registrado junto con su resultado. |
Reenvío de entregas | Vuelve a enviar una solicitud POST anterior para validar la configuración o recuperarte de un problema en el sistema receptor. |
Eventos compatibles
Un webhook puede suscribirse a uno o varios eventos. Actualmente, se admiten tres eventos relacionados con la creación de contenido.
Evento | Cuándo se envía | Para qué se utiliza |
Clip creado
| Se crea un nuevo clip. | Iniciar flujos de trabajo relacionados con la creación de clips. |
GIF creado | Se crea un nuevo GIF. | Automatizar los flujos de trabajo de contenido basados en GIF. |
Imagen creada | Una nueva imagen es creada. | Automatizar los flujos de trabajo de creación de imágenes. |
Cómo crear un webhook
Los webhooks se crean y administran desde la sección Desarrollador de la configuración de tu organización, debajo de la tabla de claves API.
📕 Nota: La sección Desarrollador anteriormente se llamaba API. Se ha cambiado el nombre para incluir una gama más amplia de herramientas para desarrolladores.
Abre la configuración de tu organización y ve a la sección Desarrollador.
En Webhooks, selecciona CREAR WEBHOOK.
Introduce la URL del webhook, es decir, el endpoint que recibirá la solicitud POST. Debe utilizar HTTPS.
Añade una Descripción para indicar para qué se utilizará el endpoint.
En Eventos, selecciona uno o varios eventos del menú desplegable.
Guarda el webhook. Aparecerá en la tabla de Webhooks.
Copia la clave secreta de firma que se muestra y guárdala en un lugar seguro. La necesitarás para verificar las entregas.
📕 Nota: La clave secreta de firma se muestra una sola vez. No podrás volver a verla y Grabyo tampoco podrá recuperarla por ti. Trátala como una contraseña. Guárdala en un gestor de secretos o una herramienta similar y nunca la incluyas en el código fuente, en los registros del sistema ni en un ticket de soporte. Si la pierdes, tendrás que eliminar el webhook y crear uno nuevo.
Administración de webhooks
La tabla de Webhooks muestra todos los webhooks de la organización, junto con su descripción, URL, eventos suscritos y estado. Un webhook puede estar Activo o Inactivo.
Selecciona el menú de opciones al final de la fila de un webhook para ver las acciones disponibles.
Acción | Para qué se utiliza |
Desactivar | Desactivar el webhook. |
Entregas | Abrir el historial de entregas del webhook. |
Eliminar webhook | Eliminar el webhook. |
📕 Nota: Un webhook puede pasar automáticamente al estado Inactivo si los intentos de entrega fallan repetidamente. Corrige el problema en tu endpoint, vuelve a enviar una entrega para comprobar que funciona correctamente y, después, reactiva el webhook.
Ejemplo de solicitud POST
Cuando se produce un evento al que está suscrito el webhook, Grabyo envía una solicitud HTTP POST a la URL configurada. Este es el cuerpo de la solicitud que se envía cuando se crea un clip.
{ "id": "String",
"type": "clip.created",
"version": "1",
"publishedAt": "2026-09-07T09:42:10.211Z",
"data": {
"assetId": "String",
"campaignId": "String",
"streamId": "String",
"title": "example title",
"description": "example description",
"mediaUrl": "String",
"thumbnailUrl": "String",
"createdAt": "2026-09-07T09:41:35.221Z"
}
}mediaUrl y thumbnailUrl son las URL de descarga del archivo multimedia y su miniatura, respectivamente.
Los enlaces a los archivos multimedia caducan después de 24 horas: mediaUrl y thumbnailUrl son URL firmadas previamente que tienen una validez de 24 horas desde el momento en que se produce el evento. Descarga los archivos que necesites en cuanto recibas el evento. No guardes los enlaces esperando que sigan funcionando más adelante. Los reintentos y reenvíos utilizan los mismos enlaces y mantienen la misma fecha de caducidad. Por lo tanto, si vuelves a enviar una entrega más de 24 horas después del evento, los enlaces ya no funcionarán.
Verificación de las entregas
La URL de tu webhook es pública, por lo que cualquier persona que la conozca puede enviar una solicitud que parezca provenir de Grabyo. Cada entrega incluye una firma generada con la clave secreta de tu webhook, lo que te permite comprobar que la solicitud realmente proviene de Grabyo antes de procesarla. Verifica la firma de cada entrega.
Cada entrega incluye una cabecera Grabyo-Signature, por ejemplo:
Grabyo-Signature: t=1787563804,v1=ad30aa27cbce97dd3c7109a25c8d24c6840f273aca11abcbc439cc96816a7e45
Paso | Que hacer |
1. Leer la cabecera | Separa los valores primero por , y después por =. t corresponde a la marca de tiempo y v1 a la firma. Ignora cualquier otro valor. Rechaza la entrega si falta alguno de estos dos valores o si t no es un número entero. |
2. Construir la cadena que se va a firmar | Concatena la marca de tiempo, un punto (.) y el cuerpo original de la solicitud sin modificar, por ejemplo, 1787563804. |
3. Calcular la firma | Calcula el HMAC-SHA256 de esa cadena utilizando la clave secreta de firma de tu webhook como clave y codifica el resultado en formato hexadecimal. |
4. Comparar | Compara el resultado con v1 mediante una función de comparación de tiempo constante, como hmac.compare_digest en Python, crypto.timingSafeEqual en Node.js o hmac.Equal en Go. No utilices una comparación simple con ==. |
5. Comprobar la marca de tiempo | Rechaza la entrega si han transcurrido más de cinco minutos desde la marca de tiempo t. Esto evita que una entrega interceptada pueda volver a enviarse posteriormente. |
📕 Nota: La mayoría de los errores de verificación ocurren porque se calcula el hash del JSON después de procesarlo y volver a serializarlo, en lugar de utilizar el cuerpo original de la solicitud. Al volver a serializar el JSON, pueden cambiar el orden de las claves y los espacios en blanco, lo que provoca que la firma no coincida. Calcula el hash utilizando exactamente los bytes recibidos, antes de procesar el JSON.
Cómo probar la verificación
Comprueba tu código utilizando estos valores. Si la implementación es correcta, generará la firma esperada.
Emtrada | Valor |
Clave secreata |
|
Marca de tiempo |
|
Cuerpo de la solicitud |
|
Firma esperada |
|
✅ Consejo: La verificación completa de este ejemplo no superará la comprobación de los cinco minutos, ya que la marca de tiempo es antigua. Esto es normal.
Requisitos del endpoint y reintentos
Tu endpoint debe cumplir los siguientes requisitos para que una entrega se considere exitosa.
Requisito | Detalles |
HTTPS | La URL del webhook debe utilizar HTTPS. |
Respuesta | Devuelve un código de estado `2xx` en un plazo máximo de **10 segundos**. Cualquier otra respuesta se considera un fallo, incluidos los tiempos de espera agotados y los códigos de estado `4xx` o `5xx`. |
Redirecciones | Las redirecciones (3xx) no se siguen y se consideran un fallo. |
Plazo para reenviar entregas | Una entrega fallida puede volver a enviarse desde el historial de entregas durante un plazo de 7 días. Después de ese periodo, el registro se elimina y el evento ya no puede volver a enviarse. |
✅ Consejo:Si el procesamiento tarda un tiempo, devuelve inmediatamente un código de estado 2xx y procesa el evento después. Así evitarás superar el límite de 10 segundos.
📕 Nota: Cada intento de entrega tiene su propia cabecera Grabyo-Delivery-Id. Inclúyela cuando contactes con el equipo de soporte por un problema con una entrega, para que podamos localizar rápidamente el intento correspondiente.
Entregas duplicadas y fuera de orden
Los webhooks se entregan al menos una vez, por lo que un mismo evento puede recibirse varias veces o llegar fuera de orden.
Situación | Cómo gestionarla |
Entregas duplicadas | El campo id del cuerpo de la solicitud identifica el evento y mantiene el mismo valor en los reintentos y reenvíos. Ignora cualquier evento cuyo id ya hayas procesado. |
Entregas fuera de orden | No se garantiza que los eventos lleguen en orden. Compara el valor de `publishedAt` antes de aplicar una actualización. |
Archivos multimedia editados | Al editar un archivo multimedia, se envía un evento nuevo con un nuevo id, pero con el mismo data.assetId. Esto no se considera un duplicado. |
Historial de entregas y reenvíos
Cada solicitud POST enviada a un webhook queda registrada en su historial de entregas. Para acceder a él, selecciona Entregas en el menú de opciones del webhook.
Detalles de la entrega
Abre una entrega individual para consultar lo que ocurrió.
Sección | Qué muestra |
Resultado | Detalles de la entrega, incluidos su estado y el tiempo que tardó en completarse. |
Solicitud y respuesta | La solicitud y la respuesta, incluidas sus cabeceras y el cuerpo de cada una. |
📕 Nota: Los detalles de una entrega pueden contener información confidencial. Elimina u oculta esta información antes de compartir capturas de pantalla de una entrega.
Cómo reenviar una entrega
Puedes volver a enviar una solicitud POST anterior mediante la opción REENVIAR, que aparece junto a la entrega en el historial.
✅ Tip: Use replay to validate endpoint setup, retest a fix, or recover from a temporary issue on the receiving side, without waiting for a new event to occur.
Solución de problemas
Situación | Qué comprobar | Qué hacer |
No se reciben eventos | Comprueba que el webhook exista, que estén seleccionados los eventos correctos, que su estado sea Activo y que se pueda acceder al endpoint de destino. | Confirma que esté seleccionado el tipo de evento correcto, genera un nuevo evento y revisa el historial de entregas. |
Fallos intermitentes | Los resultados de las entregas, los tiempos de respuesta, los detalles de las respuestas y el comportamiento del endpoint receptor. | Utiliza el historial de entregas para identificar un patrón en los fallos. Después de actualizar el endpoint, vuelve a enviar una entrega. |
Pruebas de configuración inicial | El historial de entregas y si tu sistema recibe correctamente la solicitud POST. | Crea un clip, GIF o imagen de prueba y revisa la solicitud POST correspondiente en el historial de entregas. |
La firma nunca coincide | Comprueba si estás calculando el hash del cuerpo original de la solicitud o del JSON procesado y vuelto a serializar. Verifica también que estés utilizando la clave secreta del webhook correcto. | Calcula el hash utilizando exactamente los bytes recibidos, antes de procesar el JSON. Por ejemplo, en Express, utiliza express.raw() en la ruta del webhook. Después, comprueba tu código con los valores de prueba de la sección Verificación de las entregas. |
La verificación funciona localmente, pero falla en producción | El reloj del servidor de producción. | Si el reloj tiene un desfase de más de cinco minutos, todas las entregas fallarán la comprobación de la marca de tiempo. Sincronízalo mediante NTP |
Tu servidor indica que la entrega se realizó correctamente, pero el historial muestra fallos | La duración de la entrega en los detalles correspondientes. | Es posible que tu endpoint esté tardando más de 10 segundos en responder. Devuelve primero un código de estado 2xx y procesa el evento después. |
El webhook está Inactivo y no lo has desactivado | Revisa las entregas recientes en el historial para identificar rechazos repetidos o solicitudes sin respuesta. | Es probable que el webhook se haya desactivado automáticamente. Corrige el problema en el endpoint, vuelve a enviar una entrega para comprobar que funciona y después reactiva el webhook. |
Has perdido la clave secreta de firma | No es necesario realizar ninguna comprobación, ya que la clave secreta no se puede recuperar. | Elimina el webhook y crea uno nuevo. Después, guarda la nueva clave secreta en un lugar seguro. |



