Webhooks

Los webhooks son la base de las funciones relacionadas con MLOps. Permiten escuchar nuevos cambios en repositorios específicos o en todos los repositorios que pertenecen a un conjunto particular de usuarios u organizaciones (no solo tus repositorios, sino cualquier repositorio).

Puede usarlos para convertir modelos automáticamente, crear bots comunitarios o configurar CI/CD para sus modelos, conjuntos de datos, Spaces y buckets (¡y mucho más!). Los webhooks también pueden disparar Jobs para automatizar tareas de cómputo en respuesta a eventos del repositorio.

La documentación de Webhooks se encuentra a continuación; también puedes consultar nuestras guías que muestran algunos casos de uso posibles de Webhooks:

• Ajusta un nuevo modelo cada vez que se actualice un conjunto de datos (Python)
• Crear un bot de discusión en el Hub, usando una API de LLM (NodeJS)
• Crear informes de calidad de metadatos (Python)
• Procesar nuevos archivos en un bucket con Jobs (CLI)
• y más por venir…

Crea tu Webhook

Puedes crear nuevos Webhooks y editar los existentes en la configuración de tus Webhooks:

Los Webhooks pueden vigilar actualizaciones de repositorios, Pull Requests, discusiones y nuevos comentarios. ¡Incluso es posible crear un Space para reaccionar a tus Webhooks!

Cargas de Webhook

Tras registrar un Webhook, se le notificará sobre nuevos eventos mediante una llamada HTTP POST a la URL de destino especificada. La carga útil está codificada en JSON.

Puedes ver el historial de cargas enviadas en la pestaña de actividad de la página de configuración de webhooks; también es posible reproducir webhooks anteriores para facilitar la depuración:

A modo de ejemplo, este es el payload completo cuando se abre una Pull Request:

{
  "event": {
    "action": "create",
    "scope": "discussion"
  },
  "repo": {
    "type": "model",
    "name": "openai-community/gpt2",
    "id": "621ffdc036468d709f17434d",
    "private": false,
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2",
      "api": "https://huggingface.co/api/models/openai-community/gpt2"
    },
    "owner": {
      "id": "628b753283ef59b5be89e937"
    }
  },
  "discussion": {
    "id": "6399f58518721fdd27fc9ca9",
    "title": "Update co2 emissions",
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2/discussions/19",
      "api": "https://huggingface.co/api/models/openai-community/gpt2/discussions/19"
    },
    "status": "open",
    "author": {
      "id": "61d2f90c3c2083e1c08af22d"
    },
    "num": 19,
    "isPullRequest": true,
    "changes": {
      "base": "refs/heads/main"
    }
  },
  "comment": {
    "id": "6399f58518721fdd27fc9caa",
    "author": {
      "id": "61d2f90c3c2083e1c08af22d"
    },
    "content": "Add co2 emissions information to the model card",
    "hidden": false,
    // Note: when `hidden` is `true`, `content` will be undefined
    "url": {
      "web": "https://huggingface.co/openai-community/gpt2/discussions/19#6399f58518721fdd27fc9caa"
    }
  },
  "webhook": {
    "id": "6390e855e30d9209411de93b",
    "version": 3
  }
}

Evento

La propiedad de nivel superior event siempre se especifica y se utiliza para determinar la naturaleza del evento.

Tiene dos subpropiedades: event.action y event.scope.

event.scope será uno de los siguientes valores:

• "repo" - Eventos globales en repositorios. Valores posibles para la action asociada: "create", "delete", "update", "move".
• "repo.content" - Eventos sobre el contenido del repositorio, como nuevos commits o tags. También se activa ante nuevas Pull Requests debido a la referencia/commit recién creada. Para Buckets, se activa cuando se añaden o eliminan archivos, en lugar de ante refs de Git. La action asociada es siempre "update".
• "repo.config" - Eventos sobre la configuración: actualizar secretos del Space, actualizar ajustes, actualizar DOIs, deshabilitado o no, etc. La action asociada siempre es "update".
• "discussion" - Crear una discusión o Pull Request, actualizar el título o el estado, y fusionar. Valores posibles para la action asociada: "create", "delete", "update".
• "discussion.comment" - Crear, actualizar y ocultar un comentario. Valores posibles para la action asociada: "create", "update".

Se pueden añadir más ámbitos en el futuro. Para manejar eventos desconocidos, el manejador de webhook puede considerar cualquier acción en un ámbito más restringido como una acción de "update" en el ámbito más amplio.

Por ejemplo, si en el futuro se añade el ámbito "repo.config.dois", cualquier evento con ese ámbito puede ser considerado por el manejador de webhook como una acción de "update" en el ámbito "repo.config".

Repo

En la versión actual de webhooks, la propiedad de nivel superior repo siempre se especifica, ya que los eventos siempre pueden asociarse con un repositorio. Por ejemplo, considere el siguiente valor:

"repo": {
	"type": "model",
	"name": "some-user/some-repo",
	"id": "6366c000a2abcdf2fd69a080",
	"private": false,
	"url": {
		"web": "https://huggingface.co/some-user/some-repo",
		"api": "https://huggingface.co/api/models/some-user/some-repo"
	},
	"headSha": "c379e821c9c95d613899e8c4343e4bfee2b0c600",
	"owner": {
		"id": "61d2000c3c2083e1c08af22d"
	}
}

repo.headSha es el sha del último commit en la rama main del repositorio. Solo se envía cuando event.scope comienza con "repo", no en eventos de la comunidad como discusiones y comentarios, y no para buckets, que no tienen historial de Git.

Cambios en el código

En los cambios de código, la propiedad de nivel superior updatedRefs se especifica en los eventos de repositorio. Es un array de referencias que han sido actualizadas. A continuación se muestra un valor de ejemplo:

"updatedRefs": [
  {
    "ref": "refs/heads/main",
    "oldSha": "ce9a4674fa833a68d5a73ec355f0ea95eedd60b7",
    "newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
  },
  {
    "ref": "refs/tags/test",
    "oldSha": null,
    "newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
  }
]

Las referencias recién creadas tendrán oldSha establecido en null. Las referencias eliminadas tendrán newSha establecido en null.

Puedes reaccionar a nuevos commits en solicitudes de extracción específicas, nuevas etiquetas o nuevas ramas.

Buckets

Los Buckets no son repositorios de Git: no tienen commits, ramas ni etiquetas. Los eventos de ciclo de vida (create, delete, move y actualizaciones de configuración, como la visibilidad) usan los mismos ámbitos "repo" / "repo.config" que otros tipos de repositorio.

Los cambios de archivo usan "repo.content", pero el payload tiene una propiedad updatedFiles en lugar de updatedRefs. Sobrescribir un archivo existente se informa como un "add". A continuación se muestra un ejemplo de payload después de que se añadió un archivo y se eliminó otro:

{
  "event": {
    "action": "update",
    "scope": "repo.content"
  },
  "repo": {
    "type": "bucket",
    "name": "some-user/some-bucket",
    "id": "6366c000a2abcdf2fd69a080",
    "private": false,
    "url": {
      "web": "https://huggingface.co/buckets/some-user/some-bucket",
      "api": "https://huggingface.co/api/buckets/some-user/some-bucket"
    },
    "owner": {
      "id": "61d2000c3c2083e1c08af22d"
    }
  },
  "updatedFiles": [
    {
      "path": "data/train.txt",
      "action": "add",
      "xetHash": "55faef2f2f80cd1a087c35b729f228960739441d38073cd5aa4320751e137166",
      "size": 20
    },
    {
      "path": "data/old.txt",
      "action": "delete"
    },
    ...
  ],
  "updatedFilesTruncated": true,
  "webhook": {
    "id": "6390e855e30d9209411de93b",
    "version": 3
  }
}

Con más de 10.000 entradas, la lista se acorta y updatedFilesTruncated se establece en true. En ese caso, enumera el bucket para obtener la imagen completa.

Los buckets no tienen discusiones ni Pull Requests, por lo que nunca recibirás eventos "discussion" y "discussion.comment" para ellos.

Si deseas que un cliente rastree los cambios de archivos de un bucket directamente, en lugar de a través de una callback a tu propio servidor, los buckets también exponen un live follow stream.

Cambios de configuración

Cuando la propiedad de nivel superior event.scope es "repo.config", se especifica la propiedad updatedConfig. Es un objeto que contiene la configuración actualizada. A continuación se muestra un valor de ejemplo:

"updatedConfig": {
  "private": false
}

Cuando la clave de configuración actualizada no es compatible con el webhook, el objeto estará vacío:

"updatedConfig": {}

Por ahora solo se admite private. Si te beneficiarías de que hubiera más claves de configuración aquí, infórmalo en website@huggingface.co.

Discusiones y solicitudes de extracción

La propiedad de nivel superior discussion se especifica en los eventos de la comunidad (discusiones y Pull Requests). La propiedad discussion.isPullRequest es un booleano que indica si la discusión es también un Pull Request (en el Hub, un PR es un tipo especial de discusión). Aquí hay un valor de ejemplo:

"discussion": {
	"id": "639885d811ae2bad2b7ba461",
	"title": "Hello!",
	"url": {
		"web": "https://huggingface.co/some-user/some-repo/discussions/3",
		"api": "https://huggingface.co/api/models/some-user/some-repo/discussions/3"
	},
	"status": "open",
	"author": {
		"id": "61d2000c3c2083e1c08af22d"
	},
	"isPullRequest": true,
	"changes": {
		"base": "refs/heads/main"
	}
	"num": 3
}

Comentario

La propiedad de nivel superior comment se especifica cuando se crea un comentario (incluida la creación de una discusión) o se actualiza. A continuación se muestra un valor de ejemplo:

"comment": {
	"id": "6398872887bfcfb93a306f18",
	"author": {
		"id": "61d2000c3c2083e1c08af22d"
	},
	"content": "This adds an env key",
	"hidden": false,
	"url": {
		"web": "https://huggingface.co/some-user/some-repo/discussions/4#6398872887bfcfb93a306f18"
	}
}

Secreto de webhook

Configurar un secreto de Webhook es útil para asegurarse de que las cargas enviadas a la URL de su manejador de Webhook provienen realmente de Hugging Face.

Si configuras un secreto para tu Webhook, se enviará junto con cada solicitud como un encabezado HTTP X-Webhook-Secret. Solo se admiten caracteres ASCII.

También es posible añadir el secreto directamente en la URL del handler. Por ejemplo, configurándolo como un parámetro de consulta: https://example.com/webhook?secret=XXX.

Esto puede ser útil si acceder a las cabeceras HTTP de la solicitud resulta complicado para su controlador de Webhook.

Entrega y reintentos

Los payloads de webhook se entregan de forma asincrónica, poco después de que ocurra el evento en el Hub. No se garantiza el orden: si varios eventos ocurren en un intervalo corto, es posible que lleguen fuera de secuencia.

Su handler debe confirmar la entrega con un código de estado 2xx. Cualquier otro código de estado se considera una entrega fallida, al igual que un error de conexión: se reintenta con un backoff. Si su procesamiento es lento, responda con un 2xx de inmediato y realice el trabajo de forma asíncrona, para que la entrega no se considere fallida.

Cada entrega tiene una cabecera HTTP Webhook-Id única. Las reintentos de una entrega fallida reutilizan el mismo ID, por lo que puedes tratarlo como una clave de idempotencia y procesar cada evento una sola vez.

Cuando las entregas a un Webhook siguen fallando, el Webhook se suspende automáticamente y su propietario recibe una notificación por correo electrónico. Puedes solucionarlo y volver a activarlo desde la configuración de tus Webhooks.

Limitación de tasa

Cada Webhook tiene un límite de 1.000 activaciones por cada 24 horas. Puedes ver tu uso en la página de configuración de Webhooks, en la pestaña “Activity”.

Si necesitas aumentar el número de activaciones para tu Webhook, actualiza a PRO, Team o Enterprise y contáctanos en website@huggingface.co.

Desarrollando tus Webhooks

Si no dispone de un punto final/URL HTTPS, puede probar herramientas públicas para la prueba de webhooks. Estas herramientas actúan como receptores de todos los (capture all requests) enviados y devuelven el código de estado 200 OK. Beeceptor es una herramienta que puede utilizar para crear un punto final HTTP temporal y revisar la carga entrante. Otra herramienta similar es Webhook.site.

Además, puedes enrutar una carga de Webhook real al código que se ejecuta localmente en tu máquina durante el desarrollo. Esta es una excelente manera de probar y depurar para lograr integraciones más rápidas. Puedes hacerlo exponiendo el puerto de tu localhost a Internet. Para poder seguir esta ruta, puedes usar ngrok o localtunnel.

Depuración de Webhooks

Puedes encontrar fácilmente los eventos generados recientemente para tus webhooks. Abre la pestaña de actividad de tu webhook. Allí verás la lista de eventos recientes.

Aquí puede revisar el código de estado HTTP y la carga útil de los eventos generados. Además, puede reproducir estos eventos haciendo clic en el botón Replay.

Nota: Al cambiar la URL de destino o el secreto de un Webhook, la reproducción de un evento enviará la carga útil a la URL actualizada.

Nota: Un evento reproducido se envía con el mismo Webhook-Id que la entrega original.

Preguntas frecuentes

¿Puedo definir webhooks en mi organización en lugar de en mi cuenta de usuario?

No, esto no está soportado actualmente.

¿Cómo puedo suscribirme a todos los eventos de HF (o a todos los de un tipo de repositorio, como todos los modelos)?

Esto no se expone actualmente a los usuarios finales, pero podemos activarlo para ti si envías un correo electrónico a website@huggingface.co.