# Webhook Triggers Webhook triggers let you receive HTTP requests from external services and automatically launch Valohai pipelines or executions in response. Connect Valohai with Slack, GitHub, labeling tools, or any system that can send webhooks. {% hint style="info" %} **Note:** This guide covers receiving webhooks **into Valohai** to launch work. If you want to send notifications **from Valohai** when work completes, see [Webhooks over API Requests](https://github.com/valohai/dokuhai/blob/main/webhook-over-api.md). {% endhint %} *** ## What Are Webhooks? Webhooks are HTTP POST requests that services send when events happen. They're the internet's way of saying "something happened, you should know about it." **Common webhook sources:** * **Development tools:** GitHub (code pushed), GitLab (merge requests) * **Chat platforms:** Slack (slash commands), Discord (bot commands) * **Labeling tools:** V7 (annotation complete), Label Studio (export ready) * **Monitoring systems:** Datadog (alert fired), Grafana (threshold exceeded) * **Custom applications:** Your own services and workflows *** ## Why Use Webhook Triggers? **No polling needed:** Services push events to you automatically **Real-time response:** Launch workflows immediately when events occur **Secure authentication:** Built-in support for HMAC, JWT, and token auth **Rate limiting included:** Protect against accidental runaway launches **No middleware required:** Direct integration with external services *** ## How Webhook Triggers Work Every webhook trigger has a unique URL that external services POST to. When a request arrives: 1. **Validate conditions:** All authentication and validation rules must pass 2. **Extract payload:** Request body is captured as an input file 3. **Execute actions:** Launch configured executions or pipelines 4. **Return response:** Send customizable success response to sender ### Webhook Trigger URL Format ``` https://app.valohai.com/api/v0/launch// ``` Each trigger gets a permanent, unique URL. External services POST to this URL to activate the trigger. *** ## Security and Authentication Webhook triggers support industry-standard authentication methods to verify requests are legitimate. ### Static Secret Token Simplest authentication method. The sender includes a secret token in the request (header or body), and Valohai validates it matches. **Use when:** * You control both sender and receiver * Simple shared secrets are acceptable * Quick setup is important *** ### Hash-Based Message Authentication Code (HMAC) More secure than static tokens. Both parties share a secret, but the secret isn't transmitted. Instead, the sender creates a signature from the request content using the secret, and Valohai recreates the signature to verify authenticity. **Use when:** * You need strong security * Integration with services like GitHub, Slack, Stripe * Secret should never be transmitted in requests **Benefits:** * Secret never appears in the request * Request body integrity is verified * Cannot be replayed without generating a new valid signature *** ### JSON Web Tokens (JWT) Industry-standard token format with built-in expiration. Supports both symmetric (shared secret) and asymmetric (public/private key) signing. **Use when:** * You need time-limited tokens * You want to use public key cryptography * Integration with OAuth2/OIDC systems **Benefits:** * Tokens expire automatically * Can use public/private key pairs * Rich metadata in token payload *** ### Timestamp Validation Add timestamp checks to prevent replay attacks. If a valid request is intercepted, it can't be replayed later because the timestamp will be too old. **Use when:** * Combined with HMAC for maximum security * Requests should only be valid for a short time window **How it works:** * Request includes current timestamp * Valohai checks timestamp is within tolerance (e.g., 60 seconds) * Old requests are rejected even if signature is valid *** ## Webhook Payload The webhook request body becomes an input file in your execution or pipeline. Your code can parse this payload to extract parameters, file URLs, or any other data. ### Payload Input Configuration When setting up a webhook trigger action:
**For executions:** ``` Payload Input Name Example: dataset ``` **For pipelines:** ``` Payload Input Name Example: preprocess.dataset ``` Your step must declare a matching input in `valohai.yaml`: ```yaml - step: name: preprocess inputs: - name: dataset # Receives the webhook payload ``` ### Parsing the Payload Your Python code can read and parse the payload: ```python import json import valohai with open(valohai.inputs("my-input").path()) as f: payload = json.load(f) # Extract data from payload user_id = payload["user"]["id"] file_url = payload["data"]["file_url"] ``` *** ## Rate Limiting Protect against excessive launches with rate limit conditions. Define a time **Period** (in seconds) with a maximum **Quota** of trigger launches. If launches exceed the quota, additional requests are rejected with `400 Bad Request`. **Example:** Allow 10 launches per hour * Period: 3600 seconds * Quota: 10 **Multiple rate limits:** Apply both daily and hourly limits simultaneously to prevent quota exhaustion in bursts. *** ## Common Webhook Patterns ### Pattern: Slack Slash Command **Goal:** Let team members trigger inference from Slack with `/predict ` **Components:** * Slack app with slash command * HMAC authentication using Slack signing secret * Timestamp validation for security * Execution receives Slack payload **Flow:** 1. User types `/predict https://example.com/image.jpg` in Slack 2. Slack sends webhook to Valohai trigger URL 3. Valohai validates HMAC signature and timestamp 4. Launches execution with Slack payload 5. Execution parses payload, downloads image, runs inference 6. Posts results back to Slack [**Full Slack integration guide →**](https://docs.valohai.com/automation-overview/triggers/webhooks/examples/slack-integration) *** ### Pattern: Auto-Fetch on Git Push **Goal:** Automatically fetch new commits when code is pushed to GitHub **Components:** * GitHub repository webhook * HMAC authentication with GitHub secret * Fetch repository action **Flow:** 1. Developer pushes code to GitHub 2. GitHub sends push event webhook to Valohai 3. Valohai validates GitHub signature 4. Fetches latest commit from repository 5. New commit is available for creating executions [**Full GitHub integration guide →**](https://docs.valohai.com/automation-overview/triggers/webhooks/examples/github-integration) *** ### Pattern: Process Labeled Data **Goal:** Automatically launch training when labeling is complete in V7 **Components:** * V7 workflow webhook stage * Static token authentication * Pipeline receives V7 payload with dataset information **Flow:** 1. Annotator completes labeling batch in V7 2. V7 workflow reaches webhook stage 3. Sends webhook to Valohai with annotations 4. Pipeline parses payload, downloads labeled data 5. Runs training with new annotations [**Full V7 integration guide →**](https://docs.valohai.com/automation-overview/triggers/webhooks/examples/v7-integration) *** ## Webhook vs. REST API Both can launch Valohai workloads, but they serve different purposes: | Feature | Webhook Triggers | REST API | | ------------------ | ----------------------------- | -------------------- | | **Direction** | Services call Valohai | You call Valohai | | **Authentication** | Built-in, configurable | You implement it | | **Rate limiting** | Included | You implement it | | **Setup** | Visual UI | Write code | | **Validation** | Built-in conditions | You implement it | | **Use when...** | External service sends events | You control the flow | {% hint style="info" %} **Combine them!** Use webhooks to receive events, then query the REST API to fetch additional data or update status. {% endhint %} *** ## Best Practices ### Security First * Always use authentication (HMAC, JWT, or at minimum static tokens) * Add timestamp validation to prevent replay attacks * Use HTTPS for webhook URLs (Valohai enforces this) * Keep secrets secure (environment variables, not version control) * Set reasonable rate limits ### Payload Filtering Use payload filter conditions to only trigger for specific events: * Process only specific GitHub branches * Trigger only for certain Slack users * Filter by dataset or model names ### Testing Before going live: 1. Create the trigger with authentication disabled 2. Test with manual POST requests (`curl`, Postman) 3. Verify payload parsing works correctly 4. Add authentication and test again 5. Enable rate limiting ### Monitoring * Check trigger logs regularly (Project Settings → Triggers → View Logs) * Set up notifications for failed trigger launches * Monitor execution queue depth * Track trigger launch frequency *** ## Request Method Requirement {% hint style="warning" %} **POST only:** Webhook triggers only accept POST requests. GET, PUT, DELETE, and other methods are rejected. {% endhint %} *** ## Next Steps * **Ready to build?** Follow the [Launch Pipelines with Webhooks](https://docs.valohai.com/automation-overview/triggers/webhooks/webhook-pipeline) quickstart * **Need authentication help?** Read the [Webhook Triggers Reference](https://docs.valohai.com/automation-overview/triggers/webhooks/webhook-reference) * **Want examples?** Check out [Slack](https://docs.valohai.com/automation-overview/triggers/webhooks/examples/slack-integration), [GitHub](https://docs.valohai.com/automation-overview/triggers/webhooks/examples/github-integration), and [V7](https://docs.valohai.com/automation-overview/triggers/webhooks/examples/v7-integration) integrations