Webhook Triggers
Receive webhooks from external services to launch Valohai workloads
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.
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:
Validate conditions: All authentication and validation rules must pass
Extract payload: Request body is captured as an input file
Execute actions: Launch configured executions or pipelines
Return response: Send customizable success response to sender
Webhook Trigger URL Format
https://app.valohai.com/api/v0/launch/<trigger-id>/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: datasetFor pipelines:
Payload Input Name Example: preprocess.datasetYour step must declare a matching input in valohai.yaml:
- step:
name: preprocess
inputs:
- name: dataset # Receives the webhook payloadParsing the Payload
Your Python code can read and parse the payload:
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 <url>
Components:
Slack app with slash command
HMAC authentication using Slack signing secret
Timestamp validation for security
Execution receives Slack payload
Flow:
User types
/predict https://example.com/image.jpgin SlackSlack sends webhook to Valohai trigger URL
Valohai validates HMAC signature and timestamp
Launches execution with Slack payload
Execution parses payload, downloads image, runs inference
Posts results back to Slack
Full Slack integration guide →
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:
Developer pushes code to GitHub
GitHub sends push event webhook to Valohai
Valohai validates GitHub signature
Fetches latest commit from repository
New commit is available for creating executions
Full GitHub integration guide →
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:
Annotator completes labeling batch in V7
V7 workflow reaches webhook stage
Sends webhook to Valohai with annotations
Pipeline parses payload, downloads labeled data
Runs training with new annotations
Webhook vs. REST API
Both can launch Valohai workloads, but they serve different purposes:
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
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:
Create the trigger with authentication disabled
Test with manual POST requests (
curl, Postman)Verify payload parsing works correctly
Add authentication and test again
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
POST only: Webhook triggers only accept POST requests. GET, PUT, DELETE, and other methods are rejected.
Next Steps
Ready to build? Follow the Launch Pipelines with Webhooks quickstart
Need authentication help? Read the Webhook Triggers Reference
Last updated
Was this helpful?