Hub documentation
Webhooks
Webhooks
Webhooks são a base para recursos relacionados a MLOps. Eles permitem que você monitore novas alterações em repositórios específicos ou em todos os repositórios pertencentes a um conjunto particular de usuários/organizações (não apenas seus repositórios, mas qualquer repositório).
Você pode usá-los para converter modelos automaticamente, criar bots de comunidade ou configurar CI/CD para seus modelos, datasets, Spaces e buckets (e muito mais!). Webhooks também podem disparar Jobs para automatizar tarefas de computação em resposta a eventos de repositório.
A documentação de Webhooks está abaixo – ou você também pode navegar pelos nossos guias que apresentam alguns casos de uso possíveis de Webhooks:
- Fine-tune um novo modelo sempre que um dataset for atualizado (Python)
- Crie um bot de discussão no Hub, usando uma API de LLM (NodeJS)
- Criar relatórios de qualidade de metadados (Python)
- Processar novos arquivos em um bucket com Jobs (CLI)
- e muito mais a caminho…
Crie seu Webhook
Você pode criar novos Webhooks e editar os existentes nas configurações de Webhooks:
Webhooks podem monitorar atualizações de repositórios, Pull Requests, discussões e novos comentários. É até mesmo possível criar um Space para reagir aos seus Webhooks!
Webhook Payloads
Após registrar um Webhook, você será notificado sobre novos eventos por meio de uma chamada HTTP POST na URL de destino especificada. O payload é codificado em JSON.
Você pode visualizar o histórico de payloads enviados na aba de atividade da página de configurações do webhook. Também é possível reproduzir webhooks anteriores para facilitar a depuração:
Como exemplo, aqui está o payload completo quando um Pull Request é aberto:
{
"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
A propriedade de nível superior event é sempre especificada e usada para determinar a natureza do evento.
Ele possui duas subpropriedades: event.action e event.scope.
event.scope será um dos seguintes valores:
"repo"- Eventos globais em repositórios. Valores possíveis para aactionassociada:"create","delete","update","move"."repo.content"- Eventos no conteúdo do repositório, como novos commits ou tags. Ele também é acionado por novos Pull Requests devido à referência/commit recém-criada. Para Buckets, ele é acionado quando arquivos são adicionados ou excluídos, em vez de ser acionado por refs do Git. Aactionassociada é sempre"update"."repo.config"- Eventos no config: atualizar segredos do Space, atualizar configurações, atualizar DOIs, desativado ou não, etc. Aactionassociada é sempre"update"."discussion"- Criação de uma discussão ou Pull Request, atualização do título ou status e mesclagem. Valores possíveis para a ação associadaaction:"create","delete","update"."discussion.comment"- Criar, atualizar e ocultar um comentário. Valores possíveis para oactionassociado:"create","update".
Mais escopos podem ser adicionados no futuro. Para lidar com eventos desconhecidos, o manipulador de webhook pode considerar qualquer ação em um escopo mais restrito como uma ação de "update" no escopo mais amplo.
Por exemplo, se o escopo "repo.config.dois" for adicionado no futuro, qualquer evento com esse escopo pode ser considerado pelo seu manipulador de webhook como uma ação de "update" no escopo "repo.config".
Repositório
Na versão atual dos webhooks, a propriedade de nível superior repo é sempre especificada, pois os eventos sempre podem ser associados a um repositório. Por exemplo, considere o seguinte 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 é o sha do commit mais recente no ramo main do repositório. Ele é enviado apenas quando event.scope começa com "repo", e não em eventos da comunidade, como discussões e comentários, nem para buckets, que não possuem histórico Git.
Alterações no código
Em alterações de código, a propriedade de nível superior updatedRefs é especificada em eventos de repositório. Trata-se de um array de referências que foram atualizadas. Aqui está um valor de exemplo:
"updatedRefs": [
{
"ref": "refs/heads/main",
"oldSha": "ce9a4674fa833a68d5a73ec355f0ea95eedd60b7",
"newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
},
{
"ref": "refs/tags/test",
"oldSha": null,
"newSha": "575db8b7a51b6f85eb06eee540738584589f131c"
}
]Referências recém-criadas terão oldSha definido como null. Referências excluídas terão newSha definido como null.
Você pode reagir a novos commits em pull requests específicos, novas tags ou novos branches.
Buckets
Buckets não são repositórios Git: eles não possuem commits, branches ou tags. Os eventos de ciclo de vida (create, delete, move e atualizações de configuração, como visibilidade) usam os mesmos escopos "repo" / "repo.config" que outros tipos de repositório.
As alterações de arquivo usam "repo.content", mas o payload possui uma propriedade updatedFiles em vez de updatedRefs. A sobrescrita de um arquivo existente é reportada como um "add". Aqui está um exemplo de payload após um arquivo ter sido adicionado e outro excluído:
{
"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
}
}Acima de 10.000 entradas, a lista é truncada e updatedFilesTruncated é definido como true. Nesse caso, liste o bucket para obter a visão completa.
Os Buckets não possuem discussões nem Pull Requests, portanto você nunca receberá eventos "discussion" e "discussion.comment" para eles.
Se você deseja que um cliente acompanhe as alterações de arquivos de um bucket diretamente, em vez de por meio de um callback para o seu próprio servidor, os buckets também expõem um live follow stream.
Alterações de configuração
Quando a propriedade de nível superior event.scope é "repo.config", a propriedade updatedConfig é especificada. Trata-se de um objeto contendo a configuração atualizada. Aqui está um valor de exemplo:
"updatedConfig": {
"private": false
}Quando a chave de configuração atualizada não é suportada pelo webhook, o objeto ficará vazio:
"updatedConfig": {}Por enquanto, apenas private é suportado. Se você se beneficiaria da presença de mais chaves de configuração aqui, por favor, nos informe em website@huggingface.co.
Discussões e Pull Requests
A propriedade de nível superior discussion é especificada em eventos da comunidade (discussões e Pull Requests). A propriedade discussion.isPullRequest é um booleano que indica se a discussão também é um Pull Request (no Hub, um PR é um tipo especial de discussão). Aqui está um exemplo de valor:
"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
}Comentário
A propriedade de nível superior comment é especificada quando um comentário é criado (incluindo na criação de uma discussão) ou atualizado. Aqui está um exemplo de valor:
"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"
}
}Segredo do webhook
Definir um segredo de Webhook é útil para garantir que os payloads enviados para a URL do seu manipulador de Webhook realmente sejam do Hugging Face.
Se você definir um segredo para o seu Webhook, ele será enviado junto como um cabeçalho HTTP X-Webhook-Secret em cada solicitação. Somente caracteres ASCII são suportados.
Também é possível adicionar o segredo diretamente na URL do handler. Por exemplo, definindo-o como um parâmetro de consulta: https://example.com/webhook?secret=XXX.
Isso pode ser útil se o acesso aos cabeçalhos HTTP da solicitação for complicado para o seu manipulador de Webhook.
Entrega e novas tentativas
Os payloads de webhook são entregues de forma assíncrona, pouco depois que o evento ocorre no Hub. A ordem não é garantida: se vários eventos ocorrerem em sequência, eles podem chegar fora de ordem.
Seu handler deve confirmar a entrega com um código de status 2xx. Qualquer outro código de status é considerado uma entrega falha, assim como um erro de conexão: ela é reenviada com backoff. Se o seu processamento for lento, responda com um 2xx imediatamente e execute o trabalho de forma assíncrona, para que a entrega não seja considerada falha.
Cada entrega possui um cabeçalho HTTP Webhook-Id único. As novas tentativas de uma entrega falha reutilizam o mesmo ID, portanto, você pode tratá-lo como uma chave de idempotência e processar cada evento uma única vez.
Quando as entregas a um Webhook continuam falhando, o Webhook é suspenso automaticamente e seu proprietário é notificado por e-mail. Você pode diagnosticar o problema e reativá-lo nas configurações dos seus Webhooks.
Limitação de taxa
Cada Webhook é limitado a 1.000 acionamentos a cada 24 horas. Você pode visualizar seu uso na página de configurações do Webhook, na aba “Atividade”.
Se você precisar aumentar o número de gatilhos para o seu Webhook, faça o upgrade para PRO, Team ou Enterprise e entre em contato conosco em website@huggingface.co.
Desenvolvendo seus Webhooks
Se você não tiver um endpoint/URL HTTPS, pode testar com ferramentas públicas para testes de webhook. Essas ferramentas funcionam como receptores de todos os (capturam todas as) solicitações enviadas a elas e retornam o código de status 200 OK. Beeceptor é uma ferramenta que você pode usar para criar um endpoint HTTP temporário e revisar o payload recebido. Outra ferramenta desse tipo é o Webhook.site.
Além disso, você pode rotear um payload real de Webhook para o código executado localmente na sua máquina durante o desenvolvimento. Essa é uma ótima maneira de testar e depurar para integrações mais rápidas. Você pode fazer isso expondo a porta do seu localhost para a Internet. Para poder seguir por esse caminho, você pode usar ngrok ou localtunnel.
Depuração de Webhooks
Você pode encontrar facilmente os eventos gerados recentemente para seus webhooks. Abra a aba de atividade do seu webhook. Lá, você verá a lista de eventos recentes.
Aqui você pode revisar o código de status HTTP e o payload dos eventos gerados. Além disso, você pode reproduzir esses eventos clicando no botão Replay!
Nota: Ao alterar a URL de destino ou o segredo de um Webhook, a reprodução de um evento enviará o payload para a URL atualizada.
Observação: um evento reenviado é enviado com o mesmo Webhook-Id da entrega original.
Perguntas frequentes
Posso definir webhooks na minha organização em vez da minha conta de usuário?
Não, isso não é suportado no momento.
Como posso me inscrever em todos os eventos no HF (ou em todo um tipo de repositório, como em todos os modelos)?
Isso não está atualmente exposto aos usuários finais, mas podemos ativar isso para você se você enviar um e-mail para website@huggingface.co.
Update on GitHub