How webhooks work
1
Event occurs
Call ends, agent updated, or tool called
2
Webhook triggered
BlackBox constructs HTTP POST with event payload
3
Delivery attempted
Request sent to your configured endpoint
4
Your endpoint responds
Return HTTP 200 to acknowledge
Webhook types
Event webhooks
Notify about call lifecycle events. Configured in agent’s “Webhooks” tab.Tool webhooks
Execute functions called by the agent during conversations. Configured in agent’s “Tools” tab.Tools & Functions
Complete tool configuration guide
Security
- Use HTTPS — Encrypt data in transit
- Respond quickly — Return HTTP 200 within 30 seconds
- Handle duplicates — Webhooks may be retried; use idempotency keys
- Validate payloads — Check required fields before processing
Endpoint requirements
- URL must be publicly accessible
- Cannot use localhost or loopback addresses (127.0.0.1, ::1)
What’s next
Configuring Webhooks
Setup guide
Webhook Events
Complete event reference
Testing Webhooks
Testing and debugging