Before going live with webhooks in Smartlead, it's critical to test how your system handles real-time event payloads. This ensures your application can correctly receive, validate, and process the data Smartlead sends, such as when a sending inbox disconnects or a campaign crosses the bounce threshold.
Smartlead supports sample payload testing using real test events from your account, so you can validate the entire flow—from signature verification to response handling—before using webhooks in production.
This article covers how to quickly test webhook payloads, recommended security practices, and common questions developers face during setup.
Quick Setup
Prepare your endpoint
Your webhook URL must accept HTTPS POST requests with JSON.
For a quick check, you can use a tool like webhook.site.
Add the webhook in Smartlead
Go to Settings → Webhooks, enter your endpoint URL, and choose the events you want delivered.
Trigger test events
In a test account, try actions like:
Disconnect a sending inbox
Push a campaign over the bounce threshold
Watch your endpoint or inspector for the payload and response codes.
If a User-level webhook exists, it will override Client or Campaign-level webhooks.
Make your handler idempotent (able to safely handle the same event more than once) by using the X-Request-Id.
Always return:
2xx for success
4xx for invalid requests
5xx for temporary server errors
Content-Type: application/json
X-Request-Id: a unique ID for each event
X-Webhook-Level: user | client | campaign
X-Smartlead-Signature: sha256=… (HMAC of the raw body using your signing secret)
Email account disconnected
{
"id": "evt_test_001",
"type": "email.account.disconnected",
"created_at": "2025-09-07T10:15:00Z",
"data": {
"account_id": 139919,
"email": "[email protected]",
"reason": "SMTP Failure - Host unavailable"
},
"links": { "app": "https://app.smartlead.ai" },
"meta": { "attempt": 1, "level": "user" }
}Campaign bounce threshold breached
{
"id": "evt_test_002",
"type": "campaign.bounce_threshold.breached",
"created_at": "2025-09-07T10:16:00Z",
"data": {
"campaign_id": 139919,
"threshold": 3.0,
"current_bounce_rate": 4.8,
"action": "paused"
},
"links": { "app": "https://app.smartlead.ai/app/email-campaign/139919" },
"meta": { "attempt": 1, "level": "campaign" }
}Read the raw request body.
Validate the signature in X-Smartlead-Signature.
Ensure idempotency using X-Request-Id.
Reply with a simple 200 OK and JSON response, e.g.:
{ "status": "ok" }Keep it fast: Return 2xx immediately; do heavy processing in the background.
Be idempotent: Use X-Request-Id or payload hash to prevent double-processing.
Scope awareness: User-level webhooks override Client and Campaign-level ones.
Secure it: Always verify X-Smartlead-Signature
Yes. Use test campaigns and events like inbox disconnection to simulate real events. Tools like webhook.site are useful during initial setup.
Yes. Smartlead retries webhooks if you return 5xx errors or fail to respond quickly. Always return a 2xx as soon as possible.
Yes. Use the X-Smartlead-Signature header and your secret to validate the payload integrity using HMAC SHA256.
4xx responses are treated as permanent failures—Smartlead will not retry.
Use the X-Request-Id header as a unique event identifier. Store and compare it before processing.
Currently, Smartlead supports system-defined events like sends, opens, bounces, and campaign changes. Custom triggers are not supported directly via webhook.
Need Help? Contact SupportIf you're unsure how to:
Validate webhook signatures
Debug failed deliveries
Handle repeated events
Or configure your endpoint securely
Reach out to our support team:
Email: [email protected]
Chat: Use the in-app support widget for live help