Webhooks

Webhooks merupakan fondasi untuk fitur-fitur terkait MLOps. Webhooks memungkinkan Anda untuk mendengarkan perubahan baru pada repositori tertentu atau pada semua repositori yang dimiliki oleh pengguna/organisasi tertentu yang ingin Anda ikuti. Panduan ini akan menjelaskan terlebih dahulu cara mengelola webhooks secara programatik. Kemudian, kita akan melihat bagaimana memanfaatkan huggingface_hub untuk membuat server yang mendengarkan webhooks dan mendeploynya ke Space.

Panduan ini mengasumsikan Anda sudah familiar dengan konsep webhook di Huggingface Hub. Untuk mempelajari lebih lanjut tentang webhook itu sendiri, Anda sebaiknya membaca panduan ini terlebih dahulu.

Mengelola Webhook

huggingface_hub memungkinkan Anda mengelola webhook secara programatik. Anda dapat menampilkan daftar webhook yang ada, membuat webhook baru, serta memperbarui, mengaktifkan, menonaktifkan, atau menghapusnya. Bagian ini memandu Anda melalui prosedur menggunakan fungsi API Hugging Face Hub.

Membuat Webhook

Untuk membuat webhook baru, gunakan create_webhook() dan tentukan URL tempat payload harus dikirim, event apa yang harus dipantau, serta secara opsional atur domain dan secret untuk keamanan.

from huggingface_hub import create_webhook

# Example: Creating a webhook
webhook = create_webhook(
    url="https://webhook.site/your-custom-url",
    watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}],
    domains=["repo", "discussion"],
    secret="your-secret"
)

Webhook juga dapat memicu Job untuk dijalankan di infrastruktur Hugging Face alih-alih mengirim payload ke URL. Dalam kasus ini, Anda perlu meneruskan ID dari Job sumber.

from huggingface_hub import create_webhook

# Example: Creating a webhook that triggers a Job
webhook = create_webhook(
    job_id=job_id,
    watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}],
    domains=["repo", "discussion"],
    secret="your-secret"
)

Webhook memicu Job dengan payload webhook di variabel lingkungan WEBHOOK_PAYLOAD. Secret dari Job sumber tidak disalin ke webhook. Jika Job yang dipicu membutuhkan secret (misalnya HF_TOKEN), berikan melalui secrets={"HF_TOKEN": "hf_***"}. Dengan update_webhook(), Anda harus memberikan job_id bersama dengan secrets. Secret yang terdaftar menggantikan nilai yang disimpan, string kosong menghapus secret, dan semua secret lainnya tetap dipertahankan. Untuk informasi lebih lanjut tentang Hugging Face Jobs, perangkat keras yang tersedia (CPU, GPU), dan skrip UV, lihat dokumentasi Jobs.

Daftar Webhook

Untuk melihat semua webhook yang telah Anda konfigurasikan, Anda dapat mencantumkannya dengan list_webhooks(). Ini berguna untuk meninjau ID, URL, dan status mereka.

from huggingface_hub import list_webhooks

# Example: Listing all webhooks
webhooks = list_webhooks()
for webhook in webhooks:
    print(webhook)

Memperbarui Webhook

Jika Anda perlu mengubah konfigurasi webhook yang sudah ada, seperti URL atau event yang dipantau, Anda dapat memperbaruinya menggunakan update_webhook().

from huggingface_hub import update_webhook

# Example: Updating a webhook
updated_webhook = update_webhook(
    webhook_id="your-webhook-id",
    url="https://new.webhook.site/url",
    watched=[{"type": "user", "name": "new-username"}],
    domains=["repo"]
)

Mengaktifkan dan Menonaktifkan Webhooks

Anda mungkin ingin menonaktifkan webhook secara sementara tanpa menghapusnya. Hal ini dapat dilakukan menggunakan disable_webhook(), dan webhook dapat diaktifkan kembali nanti dengan enable_webhook().

from huggingface_hub import enable_webhook, disable_webhook

# Example: Enabling a webhook
enabled_webhook = enable_webhook("your-webhook-id")
print("Enabled:", enabled_webhook)

# Example: Disabling a webhook
disabled_webhook = disable_webhook("your-webhook-id")
print("Disabled:", disabled_webhook)

Menghapus Webhook

Ketika webhook tidak lagi diperlukan, webhook tersebut dapat dihapus secara permanen menggunakan delete_webhook().

from huggingface_hub import delete_webhook

# Example: Deleting a webhook
delete_webhook("your-webhook-id")

Mengelola Webhook dari CLI

Semua operasi di atas juga tersedia dari antarmuka baris perintah hf. Ini sangat berguna untuk scripting dan alur kerja agentic.

# List all webhooks
>>> hf webhooks ls

# Get details about a specific webhook
>>> hf webhooks info <webhook_id>

# Create a webhook that pings a URL
>>> hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased --domain repo

# Create a webhook that triggers a Job
>>> hf webhooks create --job-id <job_id> --watch user:julien-c

# Create a webhook that triggers a Job with your HF token as a secret
>>> hf webhooks create --job-id <job_id> --watch bucket:my-org/my-bucket --secrets HF_TOKEN

# Update an existing webhook
>>> hf webhooks update <webhook_id> --url https://new-url.com/hook

# Enable / disable a webhook
>>> hf webhooks enable <webhook_id>
>>> hf webhooks disable <webhook_id>

# Delete a webhook (with confirmation prompt)
>>> hf webhooks delete <webhook_id>

Opsi --watch menggunakan format type:name di mana type adalah salah satu dari model, dataset, space, org, atau user. Opsi ini dapat diulang untuk memantau beberapa item. Untuk daftar lengkap opsi, jalankan hf webhooks <command> --help. Untuk detail lebih lanjut, lihat panduan CLI.

Server Webhooks

Kelas dasar yang akan kita gunakan dalam bagian panduan ini adalah WebhooksServer(). Ini adalah kelas untuk mengonfigurasi server dengan mudah yang dapat menerima webhook dari Huggingface Hub. Server ini berbasis aplikasi Gradio. Ia memiliki antarmuka pengguna untuk menampilkan instruksi bagi Anda atau pengguna Anda, serta API untuk mendengarkan webhook.

Untuk melihat contoh server webhook yang berjalan, lihat Spaces CI Bot. Ini adalah Space yang meluncurkan lingkungan sementara ketika PR dibuka pada sebuah Space.

Ini adalah fitur eksperimental. Artinya, kami masih terus bekerja untuk meningkatkan API. Perubahan yang merusak (breaking changes) mungkin akan diperkenalkan di masa depan tanpa pemberitahuan sebelumnya. Pastikan untuk mengunci (pin) versi huggingface_hub di persyaratan Anda.

Buat endpoint

Menerapkan endpoint webhook sesederhana mendekorasi sebuah fungsi. Mari kita lihat contoh pertama untuk menjelaskan konsep-konsep utamanya:

# app.py
from huggingface_hub import webhook_endpoint, WebhookPayload

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

Simpan potongan kode ini dalam file bernama 'app.py' dan jalankan dengan 'python app.py'. Anda seharusnya melihat pesan seperti ini:

Webhook secret is not defined. This means your webhook endpoints will be open to everyone.
To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization:
        `app = WebhooksServer(webhook_secret='my_secret', ...)`
For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret.
Running on local URL:  http://127.0.0.1:7860
Running on public URL: https://1fadb0f52d8bf825fc.gradio.live

This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces

Webhooks are correctly setup and ready to use:
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training
Go to https://huggingface.co/settings/webhooks to setup your webhooks.

Bagus! Anda baru saja meluncurkan server webhook! Mari kita uraikan apa yang terjadi:

1. Dengan mendekorasi fungsi menggunakan webhook_endpoint(), objek WebhooksServer() telah dibuat di latar belakang. Seperti yang dapat Anda lihat, server ini adalah aplikasi Gradio yang berjalan di http://127.0.0.1:7860. Jika Anda membuka URL ini di browser, Anda akan melihat halaman pendaratan dengan instruksi tentang webhook yang terdaftar.
2. Aplikasi Gradio adalah server FastAPI di baliknya. Rute POST baru /webhooks/trigger_training telah ditambahkan ke dalamnya. Rute ini akan mendengarkan webhook dan menjalankan fungsi trigger_training saat dipicu. FastAPI akan secara otomatis memparse payload dan meneruskannya ke fungsi sebagai objek WebhookPayload. Ini adalah objek pydantic yang berisi semua informasi tentang peristiwa yang memicu webhook.
3. Aplikasi Gradio juga membuka terowongan untuk menerima permintaan dari internet. Ini adalah bagian yang menarik: Anda dapat mengonfigurasi Webhook di https://huggingface.co/settings/webhooks yang mengarah ke mesin lokal Anda. Ini berguna untuk debugging server webhook Anda dan iterasi cepat sebelum mendeploynya ke Space.
4. Terakhir, log juga memberi tahu Anda bahwa server Anda saat ini tidak diamankan oleh rahasia. Hal ini tidak menjadi masalah untuk debugging lokal, tetapi perlu diingat untuk penggunaan selanjutnya.

Secara default, server dimulai di akhir skrip Anda. Jika Anda menjalankannya di notebook, Anda dapat memulai server secara manual dengan memanggil decorated_function.launch(). Karena server unik digunakan, Anda hanya perlu memulai server sekali meskipun Anda memiliki beberapa endpoint.

Konfigurasi Webhook

Sekarang bahwa Anda memiliki server webhook yang berjalan, Anda ingin mengonfigurasi Webhook untuk mulai menerima pesan. Buka https://huggingface.co/settings/webhooks, klik “Add a new webhook” dan konfigurasikan Webhook Anda. Atur repositori target yang ingin Anda pantau dan URL Webhook, di sini https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training.

Dan selesai! Anda sekarang dapat memicu webhook tersebut dengan memperbarui repositori target (misalnya, push sebuah commit). Periksa tab Activity dari Webhook Anda untuk melihat event yang telah dipicu. Sekarang bahwa Anda memiliki setup yang berfungsi, Anda dapat mengujinya dan melakukan iterasi dengan cepat. Jika Anda memodifikasi kode Anda dan memulai ulang server, URL publik Anda mungkin berubah. Pastikan untuk memperbarui konfigurasi webhook di Hub jika diperlukan.

Deploy ke Space

Sekarang Anda sudah memiliki server webhook yang berfungsi, tujuannya adalah untuk mendeploynya ke Space. Buka https://huggingface.co/new-space untuk membuat Space. Beri nama, pilih Gradio SDK, dan klik “Create Space”. Unggah kode Anda ke Space dalam file bernama app.py. Space Anda akan dimulai secara otomatis! Untuk detail lebih lanjut tentang Spaces, silakan lihat panduan ini.

Server webhook Anda sekarang berjalan di Space publik. Dalam kebanyakan kasus, Anda akan ingin mengamankannya dengan secret. Buka pengaturan Space Anda > bagian “Repository secrets” > “Add a secret”. Atur variabel lingkungan WEBHOOK_SECRET ke nilai pilihan Anda. Kembali ke pengaturan Webhooks dan atur secret dalam konfigurasi webhook. Sekarang, hanya permintaan dengan secret yang benar yang akan diterima oleh server Anda.

Dan ini dia! Space Anda kini siap menerima webhook dari Hub. Harap diingat bahwa jika Anda menjalankan Space pada perangkat keras gratis ‘cpu-basic’, Space tersebut akan dimatikan setelah 48 jam tidak aktif. Jika Anda membutuhkan Space yang permanen, sebaiknya pertimbangkan untuk mengatur ke perangkat keras yang ditingkatkan.

Penggunaan lanjutan

Panduan di atas menjelaskan cara tercepat untuk mengatur WebhooksServer(). Pada bagian ini, kita akan melihat cara untuk menyesuaikannya lebih lanjut.

Berbagai endpoint

Anda dapat mendaftarkan beberapa endpoint pada server yang sama. Misalnya, Anda mungkin ingin memiliki satu endpoint untuk memicu pekerjaan pelatihan dan satu lagi untuk memicu evaluasi model. Anda dapat melakukan ini dengan menambahkan beberapa dekorator @webhook_endpoint:

# app.py
from huggingface_hub import webhook_endpoint, WebhookPayload

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

@webhook_endpoint
async def trigger_evaluation(payload: WebhookPayload) -> None:
    if payload.repo.type == "model" and payload.event.action == "update":
        # Trigger an evaluation job if a model is updated
        ...

Yang akan membuat dua endpoint:

(...)
Webhooks are correctly setup and ready to use:
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation

Server kustom

Untuk mendapatkan fleksibilitas lebih, Anda juga dapat membuat objek WebhooksServer() secara langsung. Ini berguna jika Anda ingin menyesuaikan halaman pendaratan server Anda. Anda dapat melakukannya dengan meneruskan Gradio UI yang akan menimpa halaman bawaan. Misalnya, Anda dapat menambahkan instruksi untuk pengguna Anda atau menambahkan formulir untuk memicu webhook secara manual. Saat membuat WebhooksServer(), Anda dapat mendaftarkan webhook baru menggunakan dekorator add_webhook().

Berikut adalah contoh lengkap:

import gradio as gr
from fastapi import Request
from huggingface_hub import WebhooksServer, WebhookPayload

# 1. Define  UI
with gr.Blocks() as ui:
    ...

# 2. Create WebhooksServer with custom UI and secret
app = WebhooksServer(ui=ui, webhook_secret="my_secret_key")

# 3. Register webhook with explicit name
@app.add_webhook("/say_hello")
async def hello(payload: WebhookPayload):
    return {"message": "hello"}

# 4. Register webhook with implicit name
@app.add_webhook
async def goodbye(payload: WebhookPayload):
    return {"message": "goodbye"}

# 5. Start server (optional)
app.launch()

1. Kami mendefinisikan UI kustom menggunakan Gradio blocks. UI ini akan ditampilkan di halaman pendaratan server.
2. Kami membuat objek WebhooksServer() dengan UI kustom dan secret. Secret bersifat opsional dan dapat diatur dengan variabel lingkungan WEBHOOK_SECRET.
3. Kami mendaftarkan webhook dengan nama eksplisit. Hal ini akan membuat endpoint di /webhooks/say_hello.
4. Kami mendaftarkan webhook dengan nama implisit. Hal ini akan membuat endpoint di /webhooks/goodbye.
5. Kami memulai server. Ini bersifat opsional karena server Anda akan dimulai secara otomatis di akhir skrip.