[Feat] Webhook server

[Wauplin]

This PR adds a new WebhookServer object to create and run a server that can handle HF Webhooks. Is it based on top of Gradio and FastAPI. The main goal is to ease setting up a Space to handle webhooks.

Initially started the discussion on slack (internal link) cc @abidlabs @freddyaboulton @davanstrien @merveenoyan who showed some interest back in February. Please let me know if you have any feedback (design-wise, API-wise, doc-wise,...)

@LysandreJik @julien-c @osanseviero Most of the code/content is already written but before a thorough review I think it's best to wait for a high-level feedback :)

Main features:

1. UI: the app has a UI based on Gradio. Default UI prints the endpoints and some instructions but the user can define its own UI manually.
2. Secrets: the app handles webhook secrets. All webhook endpoints are protected with a user-defined webhook_secret (or WEBHOOK_SECRET environment variable)
3. Debug => gradio tunnel allows for local debugging i.e. HF webhooks are processed directly on the machine => easier than debugging/editing in a Space
4. @webhook_endpoint: 1-liner to register a function as endpoint + start server quick implementation
5. WebhookServer: complete class for more flexibility
6. WebhookPayload: pydantic model for auto-validation of the payload
7. /docs: documented + testable webhooks thanks to FastAPI
8. experimental: flagged as "experimental" => warns the user the API might change => we do not commit in maintaining it if usage doesn't grow

Examples:

1. Use @webhook_endpoint => server is automatically started

from huggingface_hub import webhook_endpoint, WebhookPayload

@webhook_endpoint
async def trigger_training(payload: WebhookPayload):
    if payload.repo.type == "dataset" and payload.event.action == "update":
        # Trigger a training job if a dataset is updated
        ...

or

2. Use WebhookServer for more flexibility (custom secret/ui)

import gradio as gr
from huggingface_hub import WebhookServer, WebhookPayload

with gr.Blocks as ui:
    # custom landing page for the Space
    ...

app = WebhookServer(ui=ui, webhook_secret="my_secret_key")

@app.add_webhook("/say_hello")
async def hello(payload: WebhookPayload):
    return {"message": "hello"}

app.run()

TODO:

• PR description
• docstrings
• unit tests
• flag as experimental
• Space example (see https://huggingface.co/spaces/spaces-ci-bot/webhook)
• update docs (see reference)
• (once release) update guide in https://huggingface.co/docs/hub/webhooks + Space examples

[HuggingFaceDocBuilderDev]

The documentation is not available anymore as the PR was closed or merged.

[codecov]

Codecov Report

Patch coverage: 82.95% and project coverage change: -0.05 ⚠️

Comparison is base (043e37e) 84.39% compared to head (1aa8986) 84.34%.

❗ Current head 1aa8986 differs from pull request most recent head 3840ff0. Consider uploading reports for the commit 3840ff0 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1410      +/-   ##
==========================================
- Coverage   84.39%   84.34%   -0.05%     
==========================================
  Files          49       52       +3     
  Lines        5254     5430     +176     
==========================================
+ Hits         4434     4580     +146     
- Misses        820      850      +30     

Impacted Files	Coverage Δ
src/huggingface_hub/__init__.py	75.75% <ø> (ø)
src/huggingface_hub/utils/_runtime.py	56.15% <50.00%> (-0.30%)	⬇️
src/huggingface_hub/_webhooks_server.py	73.46% <73.46%> (ø)
src/huggingface_hub/_webhooks_payload.py	98.27% <98.27%> (ø)
src/huggingface_hub/constants.py	98.14% <100.00%> (+0.03%)	⬆️
src/huggingface_hub/utils/__init__.py	100.00% <100.00%> (ø)
src/huggingface_hub/utils/_experimental.py	100.00% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[julien-c]

took only a very superficial glance, but looks cool

also cc @coyotte508 for webhooks context

My only suggestion is maybe rename @as_webhook_endpoint to just the simpler @webhook_endpoint

[coyotte508]

Very cool!

[Wauplin]

@coyotte508 thanks for letting me know. I added the pinned attribute.
@julien-c yeah why not. I switched to @webhook_endpoint :)

[freddyaboulton]

You can create the fastapi app used by gradio without launching the server.

app = gr.routes.App.create_app(self.ui)

I think that will make it easier to check the webhook secret via a middleware.

[freddyaboulton]

Actually, I don't think this will work as calling launch after adding the middleware will recreate the FastAPI app and remove the middleware

[Wauplin]

I'm not using a middleware at all in the end. The add_middleware stuff was legacy code I didn't removed.

Good to know about the gr.routes.App.create_app possibility! But as you said I need the .launch() call afterwards so I'll not use it here.

[freddyaboulton]

Awesome PR @Wauplin. Tested and works great and the gradio usage is sound!

[freddyaboulton]

Actually, I don't think this will work as calling launch after adding the middleware will recreate the FastAPI app and remove the middleware

[Wauplin]

Thanks for reviewing @freddyaboulton! It was useful after all 😄 Glad you tested it as well 👍

[stevhliu]

Really nice work! 👏

Super detailed docstrings, in fact, I think the docstrings may be a bit overloaded with information 😅 and some of it would be fantastic in a how-to guide. I feel like here, users are learning about Webhooks for the first time instead of using the reference as a description of what a parameter does.

[Wauplin]

Thanks for the feedback @stevhliu !

Super detailed docstrings, in fact, I think the docstrings may be a bit overloaded with information sweat_smile and some of it would be fantastic in a how-to guide. I feel like here, users are learning about Webhooks for the first time instead of using the reference as a description of what a parameter does.

Yes, I hesitated to do a guide but felt that it would be too short. In the end I followed your advice and created this step-by-step guide. It takes major parts of the dostrings + adds a few explanations on how to deploy that to a Space.

[Wauplin]

I'm finally merging it! :)

Thanks to everyone involved 🙏