Webhooks & Event Subscriptions
Overview
Subscribe your endpoint to events. Configure webhook URLs in Settings > Developers. Every payload is signed with HMAC-SHA256 using your webhook secret.
Event types
- lead.created — New lead received
- lead.updated — Lead information changed
- deal.created — New deal in pipeline
- deal.won — Deal closed as won
- deal.lost — Deal closed as lost
- conversation.started — New conversation opened
- conversation.message — New message in a conversation
- agent.handoff — AI agent transferred to human
Payload format
{
"id": "evt_3f7b9c",
"type": "deal.won",
"created": 1712073600,
"data": {
"deal": {
"id": "deal_184",
"customer": "Mike Thompson",
"amount": 1850,
"currency": "USD"
}
}
}
Signature verification
Verify the X-Mosco-Signature header to ensure the webhook is authentic:
1. Get the raw request body
2. Compute HMAC-SHA256 with your webhook secret
3. Compare with the header value
4. Reject if they don't match
Always verify signatures in production to prevent spoofed events.