Webhooks require the Webhooks addon or an Enterprise plan. Visit your billing page to add this feature.
Accessing webhook settings
Navigate to your chatbot dashboard and select Settings → Webhooks to configure webhook endpoints.Available webhooks
Messages webhook
Triggered whenever the AI responds to a user’s query. Configuration:- Messages Webhook URL: The endpoint that receives message events
- Messages Webhook Token: Authentication token sent in the
X-WEBHOOK-TOKEN
header
- Log all AI responses to your database
- Trigger follow-up actions based on conversation content
- Sync conversations to your CRM
- Monitor chatbot performance in real-time
Escalation webhook
Triggered whenever a user escalates a conversation to human support. Configuration:- Escalation Webhook URL: The endpoint that receives escalation events
- Escalation Webhook Token: Authentication token sent in the
X-WEBHOOK-TOKEN
header
- Alert your support team immediately
- Create tickets in your helpdesk system
- Route escalations to specific team members
- Track escalation patterns and reasons
Leads webhook
Triggered whenever a new lead is collected via the chatbot. Configuration:- Leads Webhook URL: The endpoint that receives lead events
- Leads Webhook Token: Authentication token sent in the
X-WEBHOOK-TOKEN
header
- Add leads to your CRM automatically
- Trigger email marketing campaigns
- Notify sales team of new prospects
- Sync lead data across platforms
Configuring webhooks
- Navigate to Settings → Webhooks
- For each webhook type you want to use:
- Enter the Webhook URL (must be a valid HTTPS endpoint)
- Enter a Webhook Token (used for authentication)
- Click Save Changes
Generate a random, secure token for each webhook. This token helps you verify that requests are coming from SiteGPT and not malicious sources.
Webhook payload structure
Messages webhook payload
Escalation webhook payload
Leads webhook payload
Webhook headers
All webhook requests include these headers:Verifying webhooks
Always verify that webhook requests are coming from SiteGPT:Token verification
Check that theX-WEBHOOK-TOKEN
header matches your configured token:
Signature verification (recommended)
For additional security, verify theX-SITEGPT-SIGNATURE
header:
Handling webhook responses
Your webhook endpoint should:- Respond quickly: Return a 200 status code within 5 seconds
- Process asynchronously: Queue long-running tasks for background processing
- Handle retries: Be idempotent to handle duplicate deliveries
- Log errors: Track failures for debugging
Example endpoint (Node.js/Express)
Webhook retry policy
If your endpoint fails to respond or returns an error:- Immediate retry: After 1 second
- Second retry: After 5 seconds
- Third retry: After 30 seconds
- Final retry: After 5 minutes
Ensure your webhook endpoint is reliable and responds quickly. Repeated failures may result in webhook delivery being disabled for your chatbot.
Testing webhooks
Using webhook testing tools
Test your webhook endpoint before going live:- Webhook.site: Generate a temporary URL to inspect payloads
- ngrok: Expose your local development server to the internet
- Postman: Simulate webhook requests manually
Test payload example
Send a test request to your endpoint:Best practices
Use HTTPS endpoints only
Use HTTPS endpoints only
Webhooks must be delivered over HTTPS to ensure data security. HTTP endpoints are not supported.
Implement idempotency
Implement idempotency
Store webhook event IDs and skip processing duplicates. Network issues can cause the same webhook to be delivered multiple times.
Process asynchronously
Process asynchronously
Respond to webhooks immediately (within 5 seconds) and process data in the background to avoid timeouts.
Monitor webhook health
Monitor webhook health
Track webhook delivery success rates and set up alerts for failures.
Secure your tokens
Secure your tokens
Store webhook tokens as environment variables, never in code. Rotate tokens periodically.
Log all webhook events
Log all webhook events
Keep logs of received webhooks for debugging and audit purposes.
Common use cases
CRM integration
Support ticket creation
Analytics tracking
Troubleshooting
Webhooks not being received
Webhooks not being received
- Verify your endpoint URL is correct and accessible
- Ensure your server accepts POST requests
- Check that your endpoint uses HTTPS (not HTTP)
- Verify firewall rules allow incoming requests from SiteGPT
- Test your endpoint with curl or Postman
Receiving 401 Unauthorized errors
Receiving 401 Unauthorized errors
Webhook deliveries timing out
Webhook deliveries timing out
- Respond with 200 status immediately
- Move processing to background jobs
- Optimize database queries
- Check server response times
Receiving duplicate webhooks
Receiving duplicate webhooks
- Implement idempotency using event IDs
- Store processed webhook IDs in your database
- Skip processing if webhook ID already exists
Related features
- API Reference - Programmatic access to SiteGPT
- Zapier integration - No-code webhook alternative
- Human support - Configure escalation behavior
- Lead collection - Advanced lead capture settings