Overview
The Webhook Trigger (also called "Webhook Received") starts a workflow when an external system sends an HTTP request to your webhook endpoint.
When It Triggers
An external system sends a POST request to your webhook URL
Webhook payload is received and validated
Can be triggered by any external service or system
Use Cases
Integrate with third-party services
Receive data from external systems
Process incoming API requests
Sync data from partner systems
Handle external event notifications
Process form submissions
Connect to Zapier, Make, or other automation tools
Configuration
This trigger requires minimal configuration but provides a unique webhook URL for your workflow.
Webhook URL
Each workflow with a webhook trigger gets a unique URL:
<https://you.captainbook.io/hooks/w/{workflow-id}>Optional Configuration
Token Authentication (optional) - Add token-based authentication
Custom Headers - Validate specific headers if needed
Security
Each workflow has a unique webhook URL
Optional token authentication for additional security
Rate limiting based on your plan
Available Data
When this trigger fires, it provides the webhook payload and headers.
Context Data Structure
Payload
payload- The webhook request body (parsed as JSON/object)Contains whatever data the external system sent
Headers
headers- HTTP headers from the webhook requestIncludes standard headers (Content-Type, User-Agent, etc.)
Includes any custom headers sent by the external system
Timestamp
timestamp- Unix timestamp when webhook was received
Accessing Webhook Data
{payload.field_name}
{payload.data.id}
{headers.Content-Type}
{headers.X-Custom-Header}
{timestamp}Example Payload Structure
The payload structure depends on what the external system sends. Common formats:
{
"event": "booking.created",
"data": {
"id": 123,
"customer": "John Doe"
}
}Example Workflows
1. Process External Booking
Workflow Steps:
Trigger: Webhook Received
Action: Create Booking
Use data from
{payload}Map external fields to booking fields
2. Sync Customer Data
Workflow Steps:
Trigger: Webhook Received
Condition: If
{payload.event}equals "customer.updated"Action (True): Find Customers (by external ID)
Action: Update Customer (with new data)
3. Handle Form Submission
Workflow Steps:
Trigger: Webhook Received
Action: Create Customer
Name:
{payload.name}Email:
{payload.email}
Action: Send Notification (thank you email)
4. Process Payment Webhook
Workflow Steps:
Trigger: Webhook Received
Condition: If
{payload.status}equals "succeeded"Action (True): Get Booking (using
{payload.booking_id})Action: Update Booking (mark as paid)
5. Zapier Integration
Workflow Steps:
Trigger: Webhook Received
Action: Process data from Zapier
Action: Create or update records
Action: Send Webhook (response back to Zapier)
Testing
When testing this trigger:
Use the test modal to simulate webhook payloads
Enter JSON payload data
Add custom headers if needed
Review execution logs to see received data
Test Data
Default test data includes:
Sample payload with example fields
Common headers (Content-Type, User-Agent)
Current timestamp
You can modify test data to match your actual webhook format.
Best Practices
Validate payload - Use conditions to verify required fields exist
Handle errors - Set up error notifications for invalid webhooks
Secure endpoints - Use token authentication for sensitive workflows
Log webhooks - Review execution logs to debug issues
Rate limiting - Be aware of webhook rate limits per plan
Idempotency - Handle duplicate webhooks gracefully
Error responses - Return appropriate HTTP status codes
Webhook URL
Getting Your Webhook URL
Create a workflow with Webhook trigger
The webhook URL is displayed in the trigger configuration
Copy the URL to use in external systems
URL Format
<https://you.captainbook.io/hooks/w/{workflow-id}>Authentication
If token authentication is enabled:
Include token in request:
?token=your-tokenOr in header:
X-Webhook-Token: your-token
Rate Limits
Webhook triggers are subject to rate limits based on your plan:
Starter: 100 calls per hour
Extended: 500 calls per hour
Ultra: 2,000 calls per hour
Corporate: 10,000 calls per hour
If rate limit is exceeded, webhook requests will be rejected.
HTTP Response
Your workflow can send responses back to the webhook caller using the "Send Webhook" action, but note:
The webhook trigger itself responds immediately with 200 OK
Use "Send Webhook" for async responses to external systems